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Preface 



This book, intended mainly for the programmer coding in assembler language, describes how to 
use the services of the supervisor, the macro instructions used to request these services, and the 
linkage conventions used by the control program to provide these services. 

The system programmer interested in additional information on the supervisor should see 
MVS I Extended Architecture System Programming Library: System Macros and Facilities 
Volume i, GC28-1150 and Volume 2, GC28-1I51. 

This book is divided into two parts. Part I, "Supervisor Services," provides explanations and 
aids for using the facilities available through the supervisor. Part II, "Macro Instructions," 
provides coding information. 

Part I is divided into eight topics. Specific topics include: 



• 


Linkage Conventions 


• 


Subtask Creation and Control 


• 


Program Management 


• 


Resource Control 


• 


Program Interruption, Termination, and Dumping Services 


• 


Virtual Storage Management 


• 


Real Storage Management 


• 


Data in Virtual Facility 


• 


Miscellaneous Services 



Part II contains the descriptions and definitions of the supervisor macro instructions available 
in the assembler language. It provides applications programmers coding the assembler language 
with the information necessary to code the macro instructions. The standard, Ust, and execute 
forms of the macro instructions are grouped, where applicable, for ease of reference. 

Use of this book requires a basic knowledge of the operating system and of assembler language. 
Books that contain basic information are: 

Assembler H Version 2 Application Programming: Language Reference, GC26-4037 

MVS /Extended Architecture Checkpoint/ Restart User's Guide, CjC26-4012 

MVS/ Extended Architecture Data Administration Macro Instruction Reference, GC26-4014 

MVS/ Extended Architecture Data Administration Guide, GC26-4013 

MVS/Extended Architecture Linkage Editor and Loader User's Guide, GC26-4011 

MVS/Extended Architecture Message Library: Routing and Descriptor Codes, GC28-1194 
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MVS/Extended Architecture Operations: JES3 Commands, SC23-0063 

MVS I Extended Architecture Operations: System Commands, GC28-1206 

OS/VS2 MVS Planning: Global Resource Serialization, GC28-1062 

MVS/Extended Architecture System Programming Library: Initialization and Tuning, 
GC28-1149 

MVS /Extended Architecture System Programming Library: Service Aids, GC28-1159 

MVS/Extended Architecture System Programming Library: System Macros and Facilities 
Volume 1, GC28-1150 

MVS/Extended Architecture System Programming Library: System Macros and Facilities 
Volume 2, GC2%-n5\ 

MVS/Extended Architecture System Programming Library: System Modifications, 
GC28-1152 

Resource Access Control Facility (RACE): General Information Manual, GC28-0722 
System Programming Library: Resource Access Control Facility (RACF), SC28-1343 
370-Extended Architecture: Principles of Operation, GA22-7085 

MVS/Extended Architecture: Integrated Catalog Administration: Access Method Services 
Reference, GC26-4 135 

Notes: 

L All references to RACF in this publication indicate the program product Resource Access 
Control Facility Version 1 Release 7 (5740-XXH). 

2. All references to Assembler H in this publication indicate the program product Assembler H 
Version 2 (5668-962). 
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Parti: Supervisor Services 



Summary of Services 

The supervisor provides the resources that your programs need while assuring that as many of 
these resources as possible are being used at a given time. Well designed programs use system 
resources efficiently. Knowing the conventions and characteristics of the supervisor will help 
you design more efficient programs. 

The services you can request from the supervisor are discussed in chapters deahng with the 
following topics: 

Subtask Creation and Control: Occasionally, you can have your program executed faster and 
more efficiently by dividing parts of it into subtasks that compete with each other and with 
other tasks for execution time. 

Program Management: You can use the supervisor to aid communication between segments of 
a program. Residency and addressing mode of programs and linkage considerations for 
MVS/XA are discussed in this chapter. Save areas, addressability, and passage of control from 
one segment of a program to another are also discussed. 

Resource Control: Portions of some tasks are dependent on the completion of events in other 
tasks, thus requiring planned task synchronization. Planning is also required when more than 
one program uses a serially reusable resource. 

Program Interruption, Termination, and Dumping Services: The supervisor provides facilities for 
writing exit routines to handle specific types of interruptions. It is not likely, however, that you 
will be able to write routines to handle all types of abnormal conditions. The supervisor 
therefore provides for termination of your program when you request it by issuing an ABEND 
macro instruction, or when the control program detects a condition that will degrade the system 
or destroy data. 

Virtual Storage Management: While virtual storage allows you to write large programs without 
the need for complex overlay structures, virtual storage must be obtained for your job step. 
Virtual storage is allocated by both explicit and implicit requests. 

Real Storage Management: The supervisor administers the use of real storage and directs the 
movement of virtual pages between auxiUary storage and real storage in page size blocks. The 
services provided allow you to release virtual storage contents, load virtual storage areas into 
real storage, and page out virtual storage areas from real storage. 

In addition to the services outlined above, the supervisor provides the facilities for timing 
events, and operator communication with both the system and application programs. 
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Linkage Conventions 



You should design all programs, regardless of their function or relative position in the task, 
using certain conventions and with certain characteristics of the control program in mind. This 
chapter describes these conventions and characteristics and tells how they affect the execution 
of your program. See the "Program Management" chapter for information about linkage 
considerations for MVS/XA. 

During the execution of a program the services of another program may be required. The 
program that requests the services of another program is known as a calling program, and the 
program that was requested is known as the called program. For example, when the control 
program passes control to program A, program A becomes a called program. If program A in 
turn passes control to program B, program A becomes a calling program, and program B 
becomes a called program. From the point of view of the control program, however, program 
A remains a called program until control is returned by program A. For more information on 
this subject, see the discussion under the heading "Task and Subtask Communications" in 
"Subtask Creation and Control." 

The following conventions are presented assuming one calling and one called program. They 
apply, however, to all called and calling programs operating in the system. If the conventions 
presented here are always followed, execution of the called program will not be affected by the 
method used to pass control or by the identity of the calling program. 



Linkage Registers 

Registers 0, 1, 13, 14, and 15 are known as the linkage registers; they are used in fixed ways by 
the control program. It is good practice to use these registers in the same way in your program, 
since they may be modified by the control program or by your program when system macro 
instructions are used. Registers 2-12 are not changed by the control program. 

Registers 0 and 1 are used to pass parameters to the control program or to a called program. 
The expansions of some system macro instructions result in instructions that load a value into 
register 0 or 1 or both, or load the address of a parameter list into register 1. For other macro 
instructions, the control program uses register 1 to pass specified parameters to the program 
you call. 

Register 13 contains the address of the save area provided by the calling program. 

Register 14 contains the return address of the calling program or an address within the control 
program to which your program is to return control when it has completed execution. 

Register 15 contains the entry address when control is passed to your program by the control 
program. The entry address of the called routine should be in register 15 when you pass 
control to another program. The expansion of some macro instructions results in instructions 
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that load into register 15 the address of a parameter list to be passed to the control program. 
Register 15 is also used by the called program to return a value (a return code) to the calling 
program. 

The manner in which the control program passes the information in the PARM field of your 
EXEC statement is a good example of how the control program uses a parameter register to 
pass information. When control is passed to your program from the control program, register 1 
contains the address of a fullword on a fullword boundary in your area of virtual storage (refer 
to Figure 1). The high-order bit (bit 0) of this word is set to 1. This is a convention used by 
the control program to indicate the last word in a variable-length parameter list; you must use 
the same convention when making requests to the control program. Bits 1-31 of the fullword 
contain the address of a two-byte length field on a halfword boundary. The length field 
contains a binary count of the nimiber of bytes in the PARM field, which immediately follows 
the length field. If the PARM field was omitted in the EXEC statement, the count is set to 
zero. To prevent possible errors, the count should always be used as a length attribute in 
acquiring the information in the PARM field. If your program is not going to use this 
information immediately, you should load the address from register 1 into one of registers 2-12 
or store the address in a fullword in your program. 



Register 




2 Bytes 0 to 1 00 Bytei 

Half-Word 
Boundary 



Figure 1. Acquiring PARM Field Information 
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Saving the Calling Program^s Registers 



The first action a called program should take is to save the contents of the calUng program's 
registers. The contents of any register the called program modifies and the contents of the 
linkage registers must be saved. All registers should be saved to avoid errors when the called 
program is modified. 

The registers are saved in the 18 -word save area provided by the calling program and pointed to 
by register 13. The format of this area is shown in Figure 2. As indicated by this figure, the 
contents of each register must be saved in a specific location within the save area. Registers can 
be saved either with a store-multiple (STM) instruction or with the SAVE macro instruction. 
The store-multiple instruction, STM 14,12,12(13), places the contents of all registers except 13 
in the proper words of the save area. Saving register 13 is discussed under the heading 
"Providing a Save Area." 



Word 


Contents 


1 


Used by PL/I language program 


2 


Address of previous save area (stored by calling program) 


3 


Address of next save area (stored by current program) 


4 


Register 14 (Return address) 


5 


Register 15 (Entry address) 


6 


Register 0 


7 


Register 1 


8 


Register 2 


9 


Register 3 


10 


Register 4 


11 


Register 5 


12 


Register 6 


13 


Register 7 


14 


Register 8 


15 


Register 9 


16 


Register 10 


17 


Register 11 


18 


Register 12 



Figure 2. Fonnat of the Save Area 



The SAVE macro instruction generates instructions that store a designated group of registers in 
the save area. The registers to be saved are coded in the same order as in an STM instruction. 
Figure 3 illustrates uses of the SAVE macro instruction. The T parameter (in B) specifies that 
the contents of registers 14 and 15 are to be saved. 



(A) PROGNAME SAVE (14,12) 

(B) PROGNAME SAVE (5,10),T 



Figure 3. Use of the SAVE Macro Instruction 

The SAVE macro instruction or the equivalent instructions should be placed at the entry point 
to the program. 
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Establishing a Base Register 



In MVS/XA, addresses are resolved by adding a displacement to a base address. You must, 
therefore, establish a base register using one of the registers from 2-12 or register 15. If your 
program does not use system macro instructions and does not pass control to another program, 
you can establish a base register using the entry address in register 15. Otherwise, because both 
your program and the control program use register 15 for other purposes, you must establish a 
base using one of the registers 2-12. This should be done immediately after saving the calling 
program's registers. 

Note: Cautiously choose your base registers keeping in mind that some instructions alter 
register contents (for example, TRT alters register 2). A complete list of instructions and their 
processing is available in Principles of Operation, 



Providing a Save Area 

If any control section in your program passes control to another control section, your program 
must provide its own save area. You must also provide a save area when you use certain 
system functions, such as GET or PUT. If you establish which registers are available to the 
called program or control section, a save area is not necessary. Omitting the save area is not a 
good coding practice, however, since any changes in your program might necessitate changing a 
called program. 

Whether or not your program provides a save area, you must save the address of the calling 
program's save area, which you used, because you will need it to restore the registers before you 
return control to the program that called you. If you are not providing a save area, you can 
keep the address in register 13 or store it in a location in virtual storage. If you are creating 
your own save area, use the following procedure. 

• Store the address of the save area that you used (the address passed to you in register 13) in 
the second word of the save area you created. 

• Store the address of your save area (the address you will pass in register 13) in the third 
word of the calling program's save area. 

This procedure enables you to find the save area when you need it to restore the registers, and 
it enables a trace from save area to save area should one be necessary during a dump. 

Figure 4 and Figure 5 show two methods of obtaining a save area and of saving all the 
registers, including the addresses of the two save areas. In Figure 4 the registers are stored in 
the save area provided by the calling program by using the STM instruction. Register 12 is 
then established as the base register. The address of the caller's save area is then saved in the 
second word of the new save area, established by the DC statement. The address of the caUing 
program's save area is loaded into register 2. The address of the new save area is loaded into 
register 13, and then stored in the third word of the caller's save area. 
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PROGNAME CSECT 

PROGNAME AMODE 31 

PROGNAME RMODE 24 

STM 14,12,12(13) 

LR 12,15 

USING PROGNAME , 12 

ST 13,SAVEAREA+4 

LR 2,13 

LA 13,SAVEAREA 

ST 13,8(2) 



SAVEAREA 



DC 



18F'0' 



Figure 4. Chaining Save Areas in a Nonreenterable Program 

In Figure 5, the SAVE macro instruction is used to store registers. (An STM instruction could 
have been used.) The entry address is loaded into register 12, which is estabUshed as the base 
register. An unconditional GETMAIN macro instruction (discussed in detail under the heading 
"Virtual Storage Management") is issued requesting the control program to allocate 72 bytes of 
virtual storage from an area outside your program, and to return the address of the area in 
register 1. The addresses of the old and new save areas are stored in the assigned locations, and 
the address of the new save area is loaded into register 13. 



PROGNAME 


CSECT 




PROGNAME 


AMODE 


31 


PROGNAME 


RMODE 


24 




SAVE 


(14,12) 




LR 


12,15 




USING 


PROGNAME , 12 




GETMAIN 


R,LV=72 




ST 


13,4(1) 




ST 


1,8(13) 




LR 


13,1 



Figure 5. Chaining Save Areas in a Reenterable Program 
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Summary of Conventions to be Followed When Passing and 
Receiving Control 

The following is a list of conventions to be followed when passing and receiving control. The 
actual methods of passing control are described under the heading "Program Management." 

By a calling program before passing control (return required): 

• Place the address of your save area in register 13. 

• Place the address at which you wish to regain control (the return address) in register 14. 

• Place the entry address of the program you are calling in register 15. 

• Place the address of the parameter list (if there is one) in register 1. (Passing parameters is 
discussed under "Program Management.") 

By a calling program before passing control (no return required): 

• Restore registers 2-12 and 14. 

• Place the address of the save area provided by the program that called you in register 13. 

• Place the entry address of the program you are calling in register 15. 

• Place the addresses of parameter lists in registers 1 and 0. 
By a called program upon receiving control: 

• Save the contents of registers 0-12, 14, and 15 in the save area provided by the calling 
program. 

• EstabUsh a base register. 

• Request the control program to allocate storage for a save area if you did not already 
allocate it by using a DC statement. 

• Store the save area addresses in the assigned locations. 
By a called program before returning control: 

• Restore registers 0-12 and 14. 

• Place the address of the save area provided by the program you are returning control to in 
register 13. 

• Place a return code in register 15 if one is required. Otherwise, restore register 15. 
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Subtask Creation and Control 



One task is created in the address space by the control program as a result of initiating 
execution of the job step (the job step task). You can create additional tasks in your program. 
If you do not, however, the job step task is the only task in the address space being executed. 
The benefits of a multiprogramming environment are still available even with only one task in 
the job step; work is still being performed for other address spaces when your task is waiting 
for an event, such as an input operation, to occur. 

The advantage in creating additional tasks within the job step is that more tasks are competing 
for control. When a wait condition occurs in one of your tasks, it is not necessarily a task from 
some other address space that gets control; it may be one of your tasks, a portion of your job. 

The general rule is that parallel execution of a job step (that is, more than one task in an 
address space) should be chosen only when a significant amount of overlap between two or 
more tasks can be achieved. The amount of time taken by the control program in establishing 
and controlUng additional tasks, and your increased effort to coordinate the tasks and provide 
for communications between them must be taken into account. 



Creating the Task 

. A new task is created by issuing an ATTACH macro instruction. The task that is active when 
the ATTACH macro instruction is issued is the originating task; the newly created task is the 
subtask of the originating task. The subtask competes for control in the same manner as any 
other task in the system, on the basis of priority (both address space priority and task priority 
within the address space) and the current abihty to use a processor. The address of the task 
control block for the subtask is returned in register 1. 

If the ATTACH macro instruction is executed successfully, control is returned to the user with 
a return code of X'OO' in register 15. 

The entry point in the load module to be given control when the subtask becomes active is 
specified as it is in a LINK macro instruction, that is, through the use of the EP, EPLOC, and 
DE parameters. The use of these parameters is discussed in "Program Management." 
Parameters can be passed to the subtask using the PARAM and VL parameters, also described 
under "The LINK Macro Instruction." Additional parameters deal with the priority of the 
subtask, provide for communication between tasks, specify Ubraries to be used for program 
linkages, and estabhsh an error recovery environment for the new subtask. 

CAUTION 

All modules contained in the libraries for a job step should be uniquely named. If 
duplicate module names are contained in these libraries, the results are 
unpredictable. 
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Priorities 



There are really three priorities to consider: address space priorities, task priorities, and subtask 
priorities. 

Address Space Priority 

When each job is initiated, an address space is created. All successive steps in the job execute 
in the same address space. The address space has a dispatching priority, which is normally 
determined by the control program. The control program will select, and alter, the priority in 
order to achieve the best load balance in the system - that is, in order to make the most 
efficient use of processor time and other system resources. 

It may be desirable for some jobs to execute at a different address space priority than the 
default priority assigned by the system. To assign a priority, you code 
DPRTY = (value l,value2) on the EXEC statement. The address space priority is then 
determined as follows: 

address space dispatching priority = (value 1 x 16) + value2 

Once the address space dispatching priority is set, it can be altered only by the control program. 
(Thus, there is no limit priority associated with an address space.) However, a new address 
space priority may be set for succeeding job steps by specifying different values in the DPRTY 
parameter on the EXEC statement. 

The lEAIPSxx and lEAICSxx members of SYSl.PARMLIB can override the dispatching 
priority specified by the DPRTY parameter. The control program assigns the priority obtained 
from lEAIPSxx to jobsteps that request a dispatching priority falling within specific installation 
defined limits. lEAICSxx directs jobs into specific performance groups thereby affecting their 
priority. See SPL: Initialization and Tuning for additional information. 

Task Priority 

Each task in an address space has associated with it a Umit priority and a dispatching priority. 
These priorities are set by the control program when a job step is initiated. When other tasks 
are created in the address space by use of the ATTACH macro instruction, they may be given 
different limit and dispatching priorities by use of the LPMOD and DPMOD parameters, 
respectively. 

The task dispatching priorities of the tasks in an address space do not affect the order in which 
the jobs are selected for execution because the order is selected on the basis of address space 
dispatching priority. Once an address space is selected for dispatching, the highest priority task 
awaiting execution is selected. Thus, task priorities may affect processing within an address 
space. Note, however, that in a multiprocessing system, task priorities cannot guarantee the 
order in which the tasks will execute because more than one task may be executing 
simultaneously in the same address space on different processors. In a paging environment, 
page faults may alter the order in which the tasks execute. 
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Subtask Priority 

When a subtask is created, the limit and dispatching priorities of the subtask are the same as 
the current limit and dispatching priorities of the originating task except when the subtask 
priorities are modified by the LPMOD and DPMOD parameters of the ATTACH macro 
instruction. The LPMOD parameter specifies the number to be subtracted from the current 
limit priority of the originating task. The result of the subtraction is assigned as the limit 
priority of the subtask. If the result is zero or negative, zero is assigned as the limit priority. 
The DPMOD parameter specifies the number to be added to the current dispatching priority of 
the originating task. The result of the addition is assigned as the dispatching priority of the 
subtask, unless the number is greater than the limit priority or less than zero. In that case, the 
limit priority or 0, respectively, is used as the dispatching priority. 

Assigning and Changing Priority 

Tasks with a large number of input/output operations should be assigned a higher priority than 
tasks with little input/output, because the tasks with much input/output will be in a wait 
condition for a greater amount of time. The lower priority tasks will be executed when the 
higher priority tasks are in a wait condition. As the input/output operations are completed, the 
higher priority tasks get control, so that more I/O can be started. 

The priorities of subtasks can be changed by using the CHAP macro instruction. The CHAP 
macro instruction changes the dispatching priority of the active task or one of its subtasks by 
adding a positive or negative value. The dispatching priority of an active task can be made less 
than the dispatching priority of another task. If this occurs, if the other task is dispatchable it 
would be given control after execution of the CHAP macro instruction. 

The CHAP macro instruction can also be used to increase the limit priority of any of an active 
task's subtasks. An active task cannot change its own limit priority. The dispatching priority 
of a subtask can be raised above its own limit priority, but not above the limit of the 
originating task. When the dispatching priority of a subtask is raised above its own Umit 
priority, the subtask's limit priority is automatically raised to equal its new dispatching priority. 



Task and Subtask Communications 

The task management information in this section is required only for establishing 
communications among tasks in the same job step. The relationship of tasks in a job step is 
shown in Figure 6. The horizontal lines in Figure 6 separate originating tasks and subtasks; 
they have no bearing on task priority. Tasks A, Al, A2, A2a, B, Bl and Bla are all subtasks 
of the job-step task; tasks Al, A2, and A2a are subtasks of task A. Tasks A2a and Bla are the 
lowest level tasks in the job step. Although task Bl is at the same level as tasks Al and A2, it 
is not considered a subtask of task A. 

Task A is the originating task for both tasks Al and A2, and task A2 is the originating task for 
task A2a. A hierarchy of tasks exists within the job step. Therefore the job step task, task A, 
and task A2 are predecessors of task A2a, while task B has no direct relationship to task A2a. 
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Figure 6. Levels of Tasks in a Job Step 



All of the tasks in the job step compete independently for processor time; if no constraints are 
provided, the tasks are performed and are terminated asynchronously. However, since each 
task is performing a portion of the same job step, some communication and constraints between 
tasks are required, such as notification of the completion of subtasks. If termination of a 
predecessor task is attempted before all of the subtasks are complete, those subtasks and the 
predecessor task are abnormally terminated. 



Two parameters, the ECB and ETXR parameters, are provided in the ATTACH macro 
instruction to assist in communication between a subtask and the originating task. These 
parameters are used to indicate the normal or abnormal termination of a subtask to the 
originating task. If the ECB or ETXR parameter, or both, are coded in the ATTACH macro 
instruction, the task control block of the subtask is not removed from the system when the 
subtask is terminated. The originating task must remove the task control block from the 
system after termination of the subtask by issuing a DETACH macro instruction. If the ECB 
parameter is specified in the ATTACH macro instruction, the ECB must be in storage so that 
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the issuer of the attach can wait on it (using the WAIT macro instruction) and the control 
program can post it on behalf of the terminating task. The task control blocks for all subtasks 
must be removed before the originating task can terminate normally. 

The ETXR parameter specifies the address of an end-of-task exit routine in the originating task, 
which is to be given control when the subtask being created is terminated. The end-of-task 
routine is given control asynchronously after the subtask has terminated and must therefore be 
in virtual storage when it is required. After the control program terminates the subtask, the 
end-of-task routine specified is scheduled to be executed. It competes for CPU time using the 
priority of the originating task and of its address space and can be given control even though 
the originating task is in the wait condition. Although the DETACH macro instruction does 
not have to be issued in the end-of-task routine, this is a good place for it. 

The ECB parameter specifies the address of an event control block (discussed under "Task 
Synchronization"), which is posted by the control program when the subtask is terminated. 
After posting occurs, the event control block contains the completion code specified for the 
subtask. 

If neither the ECB nor the ETXR parameter is specified in the ATTACH macro instruction, the 
task control block for the subtask is removed from the system when the subtask is terminated. 
Its originating task does not have to issue a DETACH macro instruction. A reference to the 
task control block in a CHAP or a DETACH macro instruction in this case is risky as is task 
termination. Since the originating task is not notified of subtask termination, you may refer to 
a task control block that has been removed from the system, which would cause the active task 
to be abnormally terminated. 
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Program Management 



This chapter discusses facilities that will help you to design your programs. It includes 
descriptions of the residency mode and addressing mode of programs, linkage considerations for 
MVS/XA, load module structures, facilities for passing control between programs, and the use 
of the associated macro instructions. 



Residency and Addressing Mode of Programs 

The control program ensures that each load module is loaded above or below 16 megabytes 
(Mb) virtual as appropriate and that it is invoked in the correct addressing mode (24-bit or 
31 -bit). The placement of the module above or below 16 Mb depends on the residency mode 
(RMODE) that you define for the module. Whether a module executes in 24-bit or 31 -bit 
addressing mode depends on the addressing mode (AMODE) that you define for the module. 

When a program is executing in 24-bit addressing mode, the system treats both instruction and 
data addresses as 24-bit addresses. This allows programs executing in 24-bit addressing mode 
to address 16 megabytes (16,777,216 bytes) of storage. Similarly, when a program is executing 
in 31 -bit addressing mode, the system treats both instruction and data addresses as 31 -bit 
addresses. This allows a program executing in 31 -bit addressing mode to address 2 gigabytes 
(2,147,483,648 bytes or 128 x 16 megabytes) of storage. 

You can define the residency mode and the addressing mode of a program in the source code. 
Figure 7 shows an example of the definition of the AMODE and RMODE attributes in the 
source code. This example defines the addressing mode of the load module as 31 -bit and the 
residency mode of the load module as 24-bit. Therefore, the program will receive control in 
31 -bit addressing mode and will reside below 16 Mb. 



SAMPLE CSECT 
SAMPLE AMODE 31 
SAMPLE RMODE 24 



Figure 7. Assembler Definition of AMODE/RMODE 

Version 2 of Assembler H places the AMODE and RMODE in the external symbol dictionary 
(ESD) of the output object module for use by the linkage editor. The linkage editor passes this 
information on to the control program through the directory entry for the partitioned data set 
(PDS) that contains the load module and the composite external symbol dictionary (CESD) 
record in the load module. You can also specify the AMODE/RMODE attributes of a load 
module by using linkage editor control cards. SPL: 31-bit Addressing contains additional 
information about residency and addressing mode; Linkage Editor and Loader contains 
information about the linkage editor control cards. 
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Residency Mode Definitions 



The control program uses the RMODE attribute from the PDS directory entry for the module 
to load the program above or below 16 Mb. The RMODE attribute can have one of the 
following values: 

24 specifies that the program must reside in 24-bit addressable virtual storage. 

ANY specifies that the program can reside anywhere in virtual storage because the code has no virtual storage 
residency restrictions. 

Note: The default value for RMODE is 24. 

Addressing Mode Definitions 

The AMODE attribute, located in the PDS directory entry for the module, specifies the 
addressing mode that the module expects at entry. Bit 32 of the program status word (PSW) 
indicates the addressing mode of the program that is executing. MVS/XA supports programs 
that execute in either 24-bit or 31 -bit addressing mode. The AMODE attribute can have one of 
the following values: 

24 specifies that the program is to receive control in 24-bit addressing mode. 
31 specifies that the program is to receive control in 31 -bit addressing mode. 
ANY specifies that the program is to receive control in either 24-bit or 31-bit addressing mode. 

Note: The default value for AMODE is 24. 



Linkage Considerations for MVS/XA 

MVS/XA supports programs that execute in either 24-bit or 31 -bit addressing mode. The 
following branch instructions take addressing mode into consideration: 

Branch and link (BAL) 

Branch and link, register form (BALR) 

Branch and save (BAS) 

Branch and save, register form (BASR) 

Branch and set mode (BSM) 

Branch and save and set mode (BASSM) 

See Principles of Operation for a complete description of how these instructions function. The 
following paragraphs provide a general description of these branch instructions in MVS/XA. 

The BAL and BALR instructions are unconditional branch instructions (to the address in 
operand 2). BAL and BALR function differently depending on the addressing mode in which 
you are executing. The difference is in the linkage information passed in the link register when 
these instructions execute. In 31>bit addressing mode, the link register contains the AMODE 
indicator (bit 0) and the address of the next sequential instruction (bits 1-31); in 24-bit 
addressing mode, the link register contains the instruction length code, condition code, program 
mask, and the address of the next sequential instruction. 

BAS and BASR perform the same function that BAL and BALR perform when BAL and 
BALR execute in 31 -bit addressing mode. 
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The BSM instruction provides problem programs with a way to change the AMODE bit in the 
PSW. BSM is an unconditional branch instruction (to the address in operand 2) that saves the 
current AMODE in the high-order bit of the link register (operand 1), and sets the AMODE 
indicator in the PSW to agree with the AMODE of the address to which you are transferring 
control (that is, the high order bit of operand 2). 

The BASSM instruction functions in a manner similar to the BSM instruction. In addition to 
saving the current AMODE in the link register, setting the PSW AMODE bit, and transferring 
control, BASSM also saves the address of the next sequential instruction in the link register 
thereby providing a return address. 

BASSM and BSM are used for entry and return linkage in a rfianner similar to BALR and BR. 
The major difference from BALR and BR is that BASSM and BSM can save and change 
addressing mode. 

Passing Control Between Programs with the Same AMODE 

If you are passing control between programs that execute in the same addressing mode, there 
are several combinations of instructions that you can use. Some of these combinations are: 

Transfer Return 

BAL/BALR BR 
BAS/BASR BR 

Passing Control Between Programs with Different AMODEs 

If you are passing control between programs executing in different addressing modes, the 
AMODE indicator in the PSW must be changed. The BASSM and BSM instructions perform 
this function for you. You can transfer to a program in another AMODE using a BASSM 
instruction and then return by means of a BSM instruction. This sequence of instructions 
ensures that both programs execute in the correct AMODE. 

Figure 8 shows an example of passing control between programs with different addressing 
modes. In the example, TEST executes in 24-bit AMODE and EPl executes in 31 -bit 
AMODE. Before transferring control to EPl, the TEST program loads register 15 with EPA, 
the pointer defined entry point address (that is, the address of EPl with the high order bit set to 
1 to indicate 31 -bit AMODE). This is followed by a BASSM 14,15 instruction, which performs 
the following functions: 

• Sets the high-order bit of the link register (register 14) to 0 (because TEST is currently 
executing in 24-bit AMODE) and puts the address of the next sequential instruction into 
bits 1-31. 

• Sets the PSW AMODE bit to 1 to agree with bit 0 of register 15. 

• Transfers to EPl (the address in bits 1-31 of register 15). 
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The EPl program executes in 31 -bit AMODE. Upon completion, EPl sets a return code in 
register 15 and executes a BSM 0,14 instruction, which performs the following functions: 

• Sets the PSW AMODE bit to 0 to correspond to the high-order bit of register 14. 

• Transfers control to the address following the BASSM instruction in the TEST program. 



TEST 
TEST 
TEST 



CSECT 
AMODE 
RMODE 



24 
24 



L 15, EPA 

BASSM 14,15 



OBTAIN TRANSFER ADDRESS 
SWITCH AMODE AND TRANSFER 



EPA 



EXTRN EPl 

DC A(X' 80000000 'H-EPl) POINTER DEFINED ENTRY POINT ADDRESS 



END 



EPl CSECT 

EPl AMODE 31 

EPl RMODE ANY 



SLR 15,15 
BSM 0,14 
END 



SET RETURN CODE 0 

RETURN TO CALLER'S AMODE AND TRANSFER 



Figure 8. Example of Addressing Mode Switch 



Load Module Structure Types 



Each load module used during a job step can be designed in one of three load module 
structures: simple, planned overlay, or dynamic. A simple structure does not pass control to any 
other load modules during its execution, and is brought into virtual storage all at one time. A 
planned overlay structure may, if necessary, pass control to other load modules during its 
execution, and it is not brought into virtual storage all at one time. Instead, segments of the 
load module reuse the same area of virtual storage. A dynamic structure is brought into virtual 
storage all at one time, and passes control to other load modules during its execution. Each of 
the load modules to which control is passed can be one of the three structure types. 
Characteristics of the load module structure tj^es are summarized in Figure 9. 

Since the large capacity of virtual storage all but eUminates the need for complex overlay 
structures, planned overlays will not be discussed further. 
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Structure Type 



Loaded All at One Time 



Passes Control to Other 
Load Modules 



Simple 

Planned Overlay 
Djmamic 



Yes 
No 
Yes 



No 

Optional 
Yes 



Figure 9. Characteristics of Load Modules 



Simple Structure 



A simple structure consists of a single load module produced by the linkage editor. The single 
load module contains all of the instructions required and is paged into real storage by the 
control program as it is executed. The simple structure can be the most efficient of the two 
structure types because the instructions it uses to pass control do not require control-program 
assistance. However, you should design your program to make most efficient use of paging. 



A dynamic structure requires more than one load module during execution. Each load module 
required can operate as either a simple structure or another dynamic structure. The advantages 
of a dynamic structure over a simple structure increase as the program becomes more complex, 
particularly when the logical path of the program depends oh the data being processed. The 
load modules required in a dynamic structure are paged into real storage when required, and 
can be deleted from virtual storage when their use is completed. 



Depending on the configuration of the operating system and the macro instructions used to 
pass control, execution of the load modules is serial or in parallel. Execution is serial in the 
MVS/XA operating system unless an ATTACH macro instruction is used to create a new task. 
The new task competes for processor time independently with all other tasks in the system. The 
load module named in the ATTACH macro instruction is executed in parallel with the load 
module containing the ATTACH macro instruction. The execution of the load modules is 
serial within each task. 

The following paragraphs discuss passing control for serial execution of a load module. 
Creation and management of new tasks is discussed under the headings "Task Creation and 
Control." 



There are certain procedures to follow when passing control to' an entry point in the same load 
module. The established conventions to use when passing control are also discussed. These 
procedures and conventions are the framework for all program interfaces. Knowledge of the 
information about addressing contained in the Assembler Language publication is required. 



Dynamic Structure 



Load Module Execution 



Passing Control in a Simple Structure 
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Passing Control without Return 



Some control sections pass control to another control section of the load module and do not 
receive control back. An example of this type of control section is a housekeeping routine at 
the beginning of a program that establishes values, initiaUzes switches, and acquires buffers for 
the other control sections in the program. Use the following procedures when passing control 
without return. 

Preparing to Pass Control 

Because control will not be returned to this control section, you must restore the contents of 
register 14. Register 14 originally contained the address of the location in the calling program 
(for example, the control program) to which control is to be passed when your program is 
finished. Since the current control section does not make the return to the calling program, the 
return address must be passed on to the control section that does make the return. In addition, 
the contents of registers 2-12 must be unchanged when your program eventually returns control, 
so these registers must also be restored. 

If control were being passed to the next entry point from the control program, register 15 
would contain the entry address. You should use register 15 in the same way, so that the called 
routine remains independent of the program that passed control to it. 

Use register 1 to pass parameters. Establish a parameter list and place the address of the list in 
register 1. The parameter list should consist of consecutive fullwords starting on a fullword 
boundary, each fullword containing an address to be passed to the called control section. 
When executing in 24-bit AMODE, each address is located in the three low-order bytes of the 
word. When executing in 31 -bit AMODE, each address is located in bits 1-31 the word. In 
both addressing modes, set the high-order bit of the last word to 1 to indicate that it is the last 
word of the list. The system convention is that the Ust contain addresses only. You may, of 
course, deviate from this convention; however, when you deviate from any system convention, 
you restrict the use of your programs to those programmers who know about your special 
conventions. 

Since you have reloaded all the necessary registers, the save area that you received on entry is 
now available, and should be reused by the called control section. Pass the address of the save 
area in register 13 just as it was passed to you. By passing the address of the old save area, you 
save the 72 bytes of virtual storage for a second, unnecessary, save area. 

Note: If you pass a new save area instead of the one received on entry, errors could occur. 

Passing Control 

The common way to pass control between one control section and an entry point in the same 
load module is to load register 15 with a V-type address constant for the name of the external 
entry point, and then to branch to the address in register 15. The external entry point must 
have been identified using an ENTRY instruction in the called control section if the entry point 
is not the same as the control section's CSECT name. 

Figure 10 shows an example of loading registers and passing control. In this example, no new 
save area is used, so register 13 still contains the address of the old save area. It is also 
assumed for this example that the control section will pass the same parameters it received to 
the next entry point. First, register 14 is reloaded with the return address. Next, register 15 is 
loaded with the address of the external entry point NEXT, using the V-type address constant at 
the location NEXTADDR. Registers O-^H are reloaded, and control is passed by a branch 
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instruction using register 15. The control section to which control is passed contains an 
ENTRY instruction identifying the entry point NEXT. 



L 14,12(13) 

L 15,NEXTADDR 

LM 0,12,20(13) 

BR 15 



LOAD CALLER'S RETURN ADDRESS 
ENTRY NEXT 

RETURN CALLER'S REGISTERS 
NEXT SAVE (14,12) 



NEXTADDR DC V(NEXT) 



Figure 10. Passing Control in a Simple Structure 

Figure 1 1 shows an example of passing a parameter Ust to an entry point with the same 
addressing mode. Early in the routine the contents of register 1 (that is, the address of the 
fuUword containing the PARM field address) were stored at the fuUword PARMADDR. 
Register 13 is loaded with the address of the old save area, which had been saved in word 2 of 
the new save area. The contents of register 14 are restored, and register 15 is loaded with the 
entry address. 





USING 


*,12 


Establish addressability 


EARLY 


ST 


1 , PARMADDR 


Save parameter address 




L 


13,4(13) 


Reload address of old save area 




L 


0,20(13) 






L 


14,12(13) 


Load return address 




L 


15, NEXTADDR 


Load address of next entry point 




LA 


1, PARMLIST 


Load address of parameter list 




01 


PARMADDR,X'80' 


Turn on last parameter indicator 




LM 


2,12,28(13) 


Reload remaining registers 




BR 


15 


Pass control 


PARMLIST 


OS 


OA 




DCBADDRS 


DC 


A(INDCB) 






DC 


A(OUTDCB) 




PARMADDR 


DC 


A(0) 




NEXTADDR 


DC 


V(NEXT) 





Figure 11. Passing Control With a Parameter List 



The address of the Ust of parameters is loaded into register 1. These parameters include the 
addresses of two data control blocks (DCBs) and the original register 1 contents. The 
high-order bit in the last address parameter (PARMADDR) is set to 1 using an OR-immediate 
instruction. The contents of registers 2-12 are restored. (Since one of these registers was the 
base register, restoring the registers earUer would have made the parameter list unaddressable.) 
A branch register instruction using register 15 passes control to entry point NEXT. 
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Passing Control with Return 



The control program passed control to your program, and your program will return control 
when it is through processing. Similarly, control sections within your program will pass control 
to other control sections, and expect to receive control back. An example of this type of 
control section is a monitoring routine; the monitor determines the order of execution of other 
control sections based on the type of input data. Use the following procedures when passing 
control with return. 

Preparing to Pass Control 

Use registers 15 and 1 in the same manner they are used to pass control without return. 
Register 15 contains the entry address in the new control section and register 1 is used to pass a 
parameter list. 

Register 14 must contain the address of the location to which control is to be returned when the 
called control section completes execution. The address can be the instruction following the 
instruction which causes control to pass, or it can be another location within the current control 
section designed to handle all returns. Registers 2-12 are not involved in the passing of control; 
the called control section should not depend on the contents of these registers in any way. 

You should provide a new save area for use by the called control section as previously 
described, and pass the address of that save area in register 13. Note that the same save area 
can be reused after control is returned by the called control section. One new save area is 
ordinarily all you will require regardless of the number of control sections called. 

Passing Control 

Two standard methods are used for passing control to another control section and providing 
for return of control. One is an extension of the method used to pass control without a return, 
and requires a V-type address constant and a branch, a branch and link, or a branch and save 
instruction provided both programs execute in the same addressing mode. If the addressing 
mode changes, a branch and save and set mode instruction should be used. The other method 
uses the CALL macro instruction to provide a parameter list and establish the entry and return 
addresses. With either method, you must identify the entry point by an ENTRY instruction in 
the called control section if the entry name is not the same as the control section CSECT name. 
Figure 12 and Figure 13 illustrate the two methods of passing control; in each example, assume 
that register 13 already contains the address of a new save area. 

Figure 12 also shows the use of an inline parameter list and an answer area. The address of 
the external entry point is loaded into register 15 in the usual manner. A branch and link 
instruction is then used to branch around the parameter Ust and to load register 1 with the 
address of the parameter Ust. An inline parameter list, such as the one shown in Figure 12, is 
convenient when you are debugging because the parameters involved are located in the Usting 
(or the dump) at the point they are used, instead of at the end of the Usting or dump. Note 
that the high-order bit of the last address parameter (ANSWERAD) is set to 1 to indicate the 
end of the Ust. The area pointed to by the address in the ANSWERAD parameter is an area to 
be used by the called control section to pass parameters back to the calling control section. 
This is a possible method to use when a called control section must pass parameters back to the 
calUng control section. Parameters are passed back in this manner so that no additional 
registers are involved. The area used in this example is twelve words. Th6 size of the area for 
any specific application depends on the requirements of the two control sections involved. 
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Pass control; register 14 
contains return address 
and current AMODE 


RETURNPT 
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DC 


12F'0' 


Answer area from NEXT 



Note: This example assumes that you are passing control to a program that executes in the same addressing mode as 
your program. See the topic "Linkage Considerations for MVS/XA" for information on how to handle branches 
between programs that execute in different addressing modes. 



Figure 12. Passing Control With Return 



CALL NEXT , ( INDCB , OUTDCB , AREA ) , VL 

RETURNPT 

AREA DC 12F ' 0 ' 

Note: You cannot use the CALL macro instruction to pass control to a program that executes in a different addressing 
mode. 



Figure 13. Passing Control With CALL 

The CALL macro instruction in Figure 13 provides the same functions as the instructions in 
Figure 12. When the CALL macro instruction is expanded, the parameters cause the following 
results: 

NEXT - A V-type address constant is created for NEXT, and the address is loaded into 
register 15. 

(INDCB,OUTDCB,AREA) - A-type address constants are created for the three parameters 
coded within parentheses, and the address of the first A-type address constant is placed in 
register 1. 

VL - The high-order bit of the last A-type address constant is set to 1. 

Control is passed to NEXT using a branch and link instruction. The address of the instruction 
following the CALL macro instruction is loaded into register 14 before control is passed. 

In addition to the results described above, the V-type address constant generated by the CALL 
macro instruction requires the load module with the entry point NEXT to be link edited into 
the same load module as the control section containing the CALL macro instruction. The 
Linkage Editor and Loader publication tells more about this service. 
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The parameter list constructed from the CALL macro instruction in Figure 13, contains only 
A-type address constants. A variation on this type of parameter list results from the following 
coding: 

CALL NEXT, (INDCB, (6) , (7) ) ,VL 

In the above CALL macro instruction, two of the parameters to be passed are coded as 
registers rather than symbolic addresses. The expansion of this macro instruction again results 
in a three-word parameter list; in this example, however, the expansion also contains 
instructions that store the contents of registers 6 and 7 in the second and third words, 
respectively, of the parameter list. The high-order bit in the third word is set to 1 after register 
7 is stored. You can specify as many address parameters as you need, and you can use 
symboUc addresses or register contents as you see fit. 

Analyzing Ae Return 

When control is returned from the control program after processing a non-authorized system 
macro instruction, the contents of registers 2-13 are unchanged. When control is returned to 
your control section from the called control section, registers 2-14 contain the same information 
they contained when control was passed, as long as system conventions are followed. The 
called control section has no obligation to restore registers 0 and 1; so the contents of these 
registers may or may not have been changed. 

When control is returned, register 15 can contain a return code indicating the results of the 
processing done by the called control section. If used, the return code should be a multiple of 
four, so a branching table can be used easily, and a return code of zero should be used to 
indicate a normal return. The control program frequently uses this method to indicate the 
results of the requests you make using system macro instructions; an example of the type of 
return codes the control program provides is shown in the description of the IDENTIFY macro 
instruction. 

The meaning of each of the codes to be returned must be agreed upon in advance. In some 
cases, either a "good" or "bad" indication (zero or nonzero) will be sufficient for you to decide 
your next action. If this is true, the coding in Figure 14 could be used to analyze the results. 
Many times, however, the results and the alternatives are more comphcated, and a branching 
table, such as shown in Figure 15 could be used to pass control to the proper routine. 

Note: Explicit tests are required to ensure that the return code value does not exceed the 
branch table size. 



RETURNPT LTR 15 , 15 Test return code for zero 

BNZ ERRORTN Branch if not zero to error 
routine 



Figure 14. Test for Normal Return 
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RETURNPT B RETTAB ( 15 ) Branch to table using return 

code 

RETTAB B NORMAL Branch to normal routine 

B CONDI Branch to routine for 

condition 1 
B C0ND2 Branch to routine for 

condition 2 

B GIVEUP Branch to routine to handle 

impossible situations 



Figure 15. Return Code Test Using Branching Table 



How Control is Returned 

In the discussion of the return under "Analyzing the Return" it was indicated that the control 
section returning control must restore the contents of registers 2-14. Because these are the same 
registers reloaded when control is passed without a return, refer to the discussion under 
"Passing Control without Return" for detailed information and examples. The contents of 
registers 0 and 1 do not have to be restored. 

Register 15 can contain a return code when control is returned. As indicated previously, a 
return code should be a multiple of four with a return code of zero indicating a normal return. 
The return codes other than zero that you use can have any meaning, as long as the control 
section receiving the return codes is aware of that meaning. 

The return address is the address originally passed in register 14; you should always return 
control to that address. If an addressing mode switch is not involved, you can either use a 
branch instruction such as BR 14, or you can use the RETURN macro instruction. An 
example of each of these methods of returning control is discussed in the following paragraphs. 
If an addressing mode switch is involved, you can use a BSM 0,14 instruction to return control. 
See Figure 8 for an example that uses the BSM instruction to return control. 

Figure 16 shows a portion of a control section used to analyze input data cards and to check 
for an out-of-tolerance condition. Each time an out-of-tolerance condition is found, in addition 
to some corrective action, one is added to the one-byte value at the address STATUSBY. After 
the last data card is analyzed, this control section returns to the calUng control section, which 
bases its next action on the number of out-of-tolerance conditions encountered. The coding 
shown in Figure 16 loads register 14 with the return address. The contents of register 15 are 
set to zero, and the value at the address STATUSBY (the number of errors) is placed in the 
low-order eight bits of the register. The contents of register 15 are shifted to the left two places 
to make the value a multiple of four. Registers 2-12 are reloaded, and control is returned to 
the address in register 14. 
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Note: This example assumes that you are returning to a program with the same AMODE. If not, use the BSM 
instruction to transfer control. 



Figure 16. Establishing a Return Code 

The RETURN macro instruction saves coding time. The expansion of the RETURN macro 
instruction provides instructions that restore a designated range of registers, load a return code 
in register 15, and branch to the address in register 14. If T is specified, the RETURN macro 
instruction flags the save area used by the returning control section (that is, the save area 
supplied by the calling routine). It does this by setting the low-order bit of word four of the 
save area to one after the registers have been restored. The flag indicates that the control 
section that used the save area has returned to the calling control section. The flag is useful 
when tracing the flow of your program in a dump. For a complete record of program flow, a 
separate save area must be provided by each control section each time control is passed. 

You must restore the contents of register 13 before issuing the RETURN macro instruction. 
Code the registers to be reloaded in the same order as they would have been designated for a 
load-multiple (LM) instruction. You can load register 15 with the return code before you write 
the RETURN macro instruction, you can specify the return code in the RETURN macro 
instruction, or you can reload register 15 from the save area. 

The coding shown in Figure 17 provides the isame result as the coding shown in Figure 16. 
Registers 13 and 14 are reloaded, and the return code is loaded in register 15. The RETURN 
macro instruction reloads registers 2-12 and passes control to the address in register 14. The 
save area used is not flagged. The RC = (15) parameter indicates that register 15 already 
contains the return code, and the contents of register 15 are not to be altered. 
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Return address in 
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STATUSBY DC 
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Note: You cannot use the RETURN macro instruction to pass control to a program that executes in a different 
addressing mode. 



Figure 17. Using the RETURN Macro Instruction 

Figure 18 illustrates another use of the RETURN macro instruction. The correct save area 
address is again established, and then the RETURN macro instruction is issued. In this 
example, registers 14 and 0-12 are reloaded, a return code of 8 is placed in register 15, the save 
area is flagged, and control is returned. Specifying a return code overrides the request to 
restore register 15 even though register 15 is within the designated range of registers. 



The discussion in the preceding paragraphs has covered passing control within one load 
module, and has been based on the assumption that the load module was brought into virtual 
storage because of the program name specified in the EXEC statement. The control program 
established only one task to be performed for the job step. When the logical end of the 
program is reached, control passes to the return address passed (in register 14) to the first 
control section in the control program. When the control program receives control at this 
point, it terminates the task it created for the job step, compares the return code in register 15 
with any COND values specified on the JOB and EXEC statements, and determines whether or 
not subsequent job steps, if any are present, should be executed. 



L 

RETURN 



13,4(13) 
(14,12) ,T,RC=8 



Figure 18. RETURN Macro Instruction Witii Flag 



Return to the Control Program 
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Passing 



Control in a Dynamic Structure 



The discussion of passing control in a simple structure provides the background for the 
discussion of passing control in a dynamic structure. Within each load module, control should 
be passed as in a simple structure. If you can determine which control sections will make up a 
load module before you code the control sections, you should pass control within the load 
module without involving the control program. The macro instructions discussed in this section 
provide increased linkage capability, but they require control program assistance and possibly 
increased execution time. 



The load module containing the entry name you specified on the EXEC statement is 
automatically brought into virtual storage by the control program. The control program places 
the load module above or below 16 Mb according to its RMODE attribute. Any other load 
modules you require during your job step are brought into virtual storage by the control 
program when requested; these requests are made by using the LOAD, LINK, ATTACH, and 
XCTL macro instructions. The LOAD macro instruction sets the high-order bit of the entry 
point address to indicate the addressing mode of the load module. The ATTACH, LINK, and 
XCTL macro instructions use this information to set the addressing mode for the module that 
gets control. If the AMODE is ANY, the module will get control in the same addressing mode 
as the program that issued the ATTACH, LINK, or XCTL macro instruction. If a copy of the 
load module must be brought into storage, the control program places the load module above 
or below 16 Mb according to its RMODE attribute. The following paragraphs discuss the 
proper use of these macro instructions. 



Initially, each load module that you can obtain dynamically is located in a library (partitioned 
data set). This Ubrary is the Unk library, the job or step library, the task library, or a private 
library. 

• The link library is always present and is available to all job steps of all jobs. The control 
program provides the data control block for the hbrary and logically connects the library to 
your program, making the members of the library available to your program. 

• The job and step libraries are explicitly established by including //JOBLIB and //STEPLIB 
DD statements in the input stream. The //JOBLIB DD statement is placed immediately 
after the JOB statement, while the //STEPLIB DD statement is placed among the DD 
statements for a particular job step. The job library is available to all steps of your job, 
except those that have step Ubraries. A step library is available to a single job step; if there 
is a job library, the step library replaces the job library for the step. For either the job 
Ubrary or the step hbrary, the control program provides the data control block and issues 
the OPEN macro instruction to logically connect the Ubrary to your program. 

• Unique task Ubraries can be estabUshed by using the TASKLIB parameter of the ATTACH 
macro instruction. The issuer of the ATTACH macro instruction is responsible for 
providing the DD statement and opening the data set or sets. If the TASKLIB parameter 
is omitted, the task Ubrary of the attaching task is propagated to the attached task. In the 
following example, task A's job Ubrary is LIBl. Task A attaches task B, specifying 
TASKLIB = LIB2 in the ATTACH macro instruction. Task B's task Ubrary is 



Bringing the Load Module into Virtual Storage 



Location of tiie Load Module 
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therefore LIB2. When task B attaches task C, LIB2 is searched for task C before LIBl or 
the link library. Because task B did not specify a unique task library for task C, its own 
task library (LIB2) is propagated to task C and is the first library searched when task C 
requests that a module be brought into virtual storage. 

Task A ATTACH EP=B,TASKLIB=LIB2 
Task B ATTACH EP=C 

• A private library is defined by including a DD statement in the input stream and is 
available only to the job step in which it is defined. You must provide the data control 
block and issue the OPEN macro instruction for each data set. You may use more than 
one private Ubrary by including more than one DD statement and an associated data 
control block. 

A library can be a single partitioned data set, or a collection of such data sets. When it is a 
collection, you define each data set by a separate DD statement, but you assign a name only to 
the statement that defines the first data set. Thus, a job library consisting of three partitioned 
data sets would be defined as follows: 

//JOBLIB DD DSNAME=PDS1, . . . 
// DD DSNAME=PDS2 , . . . 

// DD DSNAME=PDS3. . . 

The three data sets (PDSl, PDS2, PDS3) are processed as one, and are said to be concatenated. 
Concatenation and the use of partitioned data sets is discussed in more detail in the Data 
Management Services publication. 

Some of the load modules from the link library may already be in virtual storage in an area 
called the link pack area. The contents of these areas are determined during the nucleus 
initialization process and will vary depending on the requirements of your installation. The link 
pack area contains all reenterable load modules from the LPA library, along with installation 
selected modules from the SVC and link libraries. These load modules can be used by any job 
step in any job. 

With the exception of those load modules contained in this area, copies of all of the reenterable 
load modules you request are brought into your area of virtual storage and are available to any 
task in your job step. The portion of your area containing the copies of the load modules is 
called the job pack area. 

The Search for the Load Module 

In response to your request for a copy of a load module, the control program searches the job 
pack area, the task's load list, and the link pack area. If a copy of the load module is found in 
one of the pack areas, the control program determines whether that copy can be used (see 
"Using an Existing Copy"). If an existing copy can be used, the search stops. If it cannot be 
used, the search continues until the module is located in a library. The load module is then 
brought into the job pack area or the load list area. 

The order in which the libraries and pack areas are searched depends on the parameters used in 
the macro instruction (LINK, LOAD, XCTL, or ATTACH) requesting the load module. The 
parameters that define the order of the search are EP, EPLOC, DE, DCB, and TASKLIB. 

The TASKLIB parameter is used only for ATTACH. You should choose the parameters for the 
macro instruction that provide the shortest search time. The search of a library actually involves 
the search of a directory, followed by copying the directory entry into virtual storage, followed 
by loading the load module into virtual storage. If you know the location of the load module, 
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you should use parameters that eliminate as many of these searches as possible, as indicated in 
Figure 19, Figure 20, and Figure 21. 

The EP, EPLOC, or DE parameter specifies the name of the entry point in the load module; 
you code one of the three every time you use a LINK, LOAD, XCTL, or ATTACH macro 
instruction. The optional DCB parameter indicates the address of the data control block for 
the library containing the load module. Omitting the DCB parameter or using the DCB 
parameter with an address of zero specifies the data control block for the task libraries, the job 
or step library, or the link library. If TASKLIB is specified and if the DCB parameter contains 
the address of the data control block for the Unk Ubrary, no other hbrary is searched. 

To avoid using "system copies" of modules resident in LPA and LINKLIB, you can specifically 
limit the search for the load module to the job pack area and the first library on the normal 
search sequence, by specifying the LSEARCH parameter on the LINK, LOAD, or XCTL 
macro instruction with the DCB for the Ubrary to be used. 

The following paragraphs discuss the order of the search when the entry name used is a member 
name. 

The EP and EPLOC parameters require the least effort on your part; you provide only the 
entry name, and the control program searches for a load module having that entry name. 
Figure 19 shows the order of the search when EP or EPLOC is coded, and the DCB parameter 
is omitted or DCB = 0 is coded. 



The job pack area is searched for an available copy. 

The requesting task's task library and all the unique task libraries of its preceding tasks are searched. (Note: For the 
ATTACH macro, the attached task's library and all the unique task libraries of its preceding tasks are searched.) 
The step library is searched; if there is no step library, the job library (if any) is searched. 
The link pack area is searched. 
The Unk library is searched. 



Figure 19. Search for Module, EP or EPLOC Parameter With DCB^O or DCB Parameter Omitted 

When used without the DCB parameter, the EP and EPLOC parameters provide the easiest 
method of requesting a load module from the link, job, or step library. The task Ubraries are 
searched before the job or step library, beginning with the task library of the task that issued 
the request and continuing through the task libraries of all its antecedent tasks. The job or step 
Ubrary is then searched, followed by the Unk Ubrary. 

A job, step, or link library or a data set in one of these Ubraries can be used to hold one version 
of a load module, while another can be used to hold another version with the same entry name. 
If one version is in the link library, you can ensure that the other will be found first by 
including it in the job or step Ubrary. However, if both versions are in the job or step Ubrary, 
you must define the data set that 

contains the version you want to use before the data set that contains the other version. For 
example, if the wanted version is in PDSl and the unwanted version is in PDS2, a step Ubrary 
consisting of these data sets should be defined as foUows: 

//STEPLIB DD DSNAME=PDS1, . . . 
// DD DSNAME=PDS2 , . . . 

If, however, the first version of a nonreusable module in the job or step Ubrary has been 
previously loaded and the version in the link Ubrary or the second version in the job Ubrary is 
desired, the DCB parameter must be coded in the macro instructions. 



Supervisor Services and Macro Instructions 



Use extreme caution when specifying module names in unique task libraries, because duplicate 
names may cause the wrong module to be brought into virtual storage when a task requests it. 
Once a module has been loaded from a task library, the module name is known to all tasks in 
the region and a copy of that module is given to all tasks requesting that that module name be 
loaded, regardless of the requester's task library. 

If you know that the load module you are requesting is a member of one of the private 
libraries, you can still use the EP or EPLOC parameter, this time in conjunction with the DCB 
parameter. You specify the address of the data control block for the private library in the DCB 
parameter. The order of the search for EP or EPLOC with the DCB parameter is shown in 
Figure 20. 



The job pack area is searched for an available copy. 
The specified library is searched. 
The Unk pack area is searched. 
The link library is searched. 



Figure 20. Search for Module, EP or EPLOC Parameters With DCB Parameter Specifying Private 
Library 

Searching a job or step library slows the retrieval of load modules from the link library; to 
speed this retrieval, you should limit the size of the job and step libraries. You can best do this 
by eliminating the job library altogether and providing step libraries where required. You can 
limit each step library to the data sets required by a single step; some steps (such as 
compilation) do not require a step library and therefore do not require searching and retrieving 
modules from the hnk library. For maximum efficiency, you should define a job library only 
when a step library would be required for every step, and every step library would be the same. 

The DE parameter requires more work than the EP and EPLOC parameters, but it can reduce 
the amount of time spent searching for a load module. Before you can use this parameter, you 
must use the BLDL macro instruction to obtain the directory entry for the module. The 
directory entry is part of the Ubrary that contains the module. 

To save time, the BLDL macro instruction must obtain directory entries for more than one 
entry name. You specify the names of the load modules and the address of the data control 
block for the library when using the BLDL macro instruction; the control program places a 
copy of the directory entry for each entry name requested in a designated location in virtual 
storage. If you specify the link library and the job or step library, the directory information 
indicates from which library the directory entry was taken. The directory entry always indicates 
the relative track and block location of the load module in the library. If the load module is 
not located on the library you indicate, a return code is given. You can then issue another 
BLDL macro instruction specifying a different library. 

To use the DE parameter, you provide the address of the directory entry and code or omit the 
DCB parameter to indicate the same library specified in the BLDL macro instruction. The task 
using the DE parameter should be the same as the one which issued the BLDL or one which 
has the same job, step, and task library structure as the task issuing the BLDL. The order of 
the search when the DE parameter is used is shown in Figure 21 for the link, job, step, and 
private Ubraries. 

The preceding discussion of the search is based on the premise that the entry name you 
specified is the member name. The control program checks for an alias entry point name when 
the load module is found in a library. If the name is an alias, the control program obtains the 
corresponding member name from the library directory, and then searches to determine if a 
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usable copy of the load module exists in the job pack area. If a usable copy does not exist in a 
pack area, a new copy is brought into the job pack area. Otherwise, the existing copy is used, 
conserving virtual storage and eliminating the loading time. 



Directory Entry Indicates Link Library and DCB = 0 or DCB Parameter Omitted. 

The job pack area for the region is searched for an available copy. 

The link pack area is searched. 

The module is obtained from the link library. 
Directory Entry Indicates Job, Step, or Task Library and DCB = 0 or DCB Parameter Omitted. 

The job pack area for the region is searched for an available copy. 

The module is obtained from the task library designated by the 'Z' byte of the DE operand. 
DCB Parameter Indicates Private Library 

The job pack area for the region is searched for an available copy. 

The module is obtained from the specified private library. 



Figure 21. Search for Module Using D£ Parameter 

As the discussion of the search indicates, you should choose the parameters for the macro 
instruction that provide the shortest search time. The search of a library actually involves a 
search of the directory, followed by copying the directory entry into virtual storage, followed by 
loading the load module into virtual storage. If you know the location of the load module, you 
should use the parameters that eliminate as many of these unnecessary searches as possible, as 
indicated in Figure 19, Figure 20, and Figure 21. Examples of the use of these figures are 
shown in the following discussion of passing control. 

Using an Existing Copy 

The control program uses a copy of the load module already in the job pack area if the copy 
can be used. Whether the copy can be used or not depends on the reusability and current 
status of the load module; that is, the load module attributes, as designated using linkage editor 
control statements, and whether the load module has already been used or is in use. The status 
information is available to the control program only when you specify the load module entry 
name on an EXEC statement, or when you use ATTACH, LINK, or XCTL macro instructions 
to transfer control to the load module. The control program protects you from obtaining an 
unusable copy of a load module if you always "formally" request a copy using these macro 
instructions (or the EXEC statement); if you pass control in any other manner (for instance, a 
branch or a CALL macro instruction), the control program, because it is not informed, cannot 
protect your copy. 

All reenterable modules (modules designated as reenterable using the Unkage editor) from any 
Ubrary are completely reusable; only one copy is ever placed in the link pack area or brought 
into your job pack area, and you get immediate control of the load module. If the module is 
serially reusable, only one copy is ever placed in the job pack area; this copy is always used for 
a LOAD macro instruction. If the copy is in use, however, and the request is made using a 
LINK, ATTACH, or XCTL macro instruction, the task requiring the load module is placed in 
a wait condition until the copy is available. A LINK macro instruction should not be issued 
for a serially reusable load module currently in use for the same task; the task will be 
abnormally terminated. (This could occur if an exit routine issued a LINK macro instruction 
for a load module in use by the main program.) 

If the load module is not reusable, a LOAD macro instruction will always bring in a new copy 
of the load module; an existing copy is used only if a LINK, ATTACH, or XCTL macro 
instruction is issued and the copy has not been used previously. Remember, the control 
program can determine if a load module has been used or is in use only if all of your requests 
are made using LINK, ATTACH, or XCTL macro instructions. 
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Using the LOAD Macro Instruction 

The LOAD macro instruction is used to ensure that a copy of the specified load module is in 
virtual storage in your region or job pack area if it was not preloaded into the link pack area. 
When a LOAD macro instruction is issued, the control program searches for the load module 
as discussed previously and brings a copy of the load module into the region if required. When 
the control program returns control, register 0 contains the addressing mode and the virtual 
storage address of the entry point specified for the requested load module, and register 1 
contains the length of the loaded module (in doublewords) and the authorization code in the 
high byte. Normally, the LOAD macro instruction is used only for a reenterable or serially 
reusable load module, since the load module is retained even though it is not in use. 

The control program also establishes a "responsibility" count for the copy, and adds one to the 
count each time the requirements of a LOAD macro instruction are satisfied by the same copy. 
As long as the responsibility count is not zero, the copy is retained in virtual storage. 

The responsibility count for the copy is lowered by one when a DELETE macro instruction is 
issued during the task which was active when the LOAD macro instruction was issued. When a 
task is terminated, the count is lowered by the number of LOAD macro instructions issued for 
the copy when the task was active minus the number of deletions. When the use count for a 
copy in a job pack area reaches zero, the virtual storage area containing the copy is made 
available. 

Passing Control with Return 

The LINK macro instruction is used to pass control between load modules and to provide for 
return of control. You can also pass control using branch, branch and link, branch and save, 
or branch and save and set mode instructions or the CALL macro instruction; however, when 
you pass control in this manner you must protect against multiple uses of nonreusable or 
serially reusable modules. You must also be careful to enter the routine in the proper 
addressing mode. The following paragraphs discuss the requirements for passing control with 
return in each case. 

The LINK Macro Instruction 

When you use the LINK macro instruction, as far as the logic of your program is concerned, 
you are passing control to another load module. Remember, however, that you are requesting 
the control program to assist you in passing control. You are actually passing control to the 
control program, using an SVC instruction, and requesting the control program to find a copy 
of the load module and pass control to the entry point you designate. There is some similarity 
between passing control using a LINK macro instruction and passing control using a CALL 
macro instruction in a simple structure. These similarities are discussed first. 

The convention regarding registers 2-12 still applies; the control program does not change the 
contents of these registers, and the called load module should restore them before control is 
returned. You must provide the address in register 13 of the save area for use by the called 
load module; the control program does not use this save area. You can pass address 
parameters in a parameter Ust to the load module using register 1; the LINK macro instruction 
provides the same facility for constructing this list as the CALL macro instruction. Register 0 
is used by the control program and the contents may be modified. In certain cases, the contents 
of register 1 may be altered by the LINK macro instruction. 

There is also some difference between passing control using a LINK macro instruction and 
passing control using a CALL macro instruction. When you pass control in a simple structure. 
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register 15 contains the entry address and register 14 contains the return address. When the 
called load module gets control, that is still what registers 14 and 15 contain, but when you use 
the LINK macro instruction, it is the control program that establishes these addresses. When 
you code the LINK macro instruction, you provide the entry name and possibly some Ubrary 
information using the EP, EPLOC, or DE, and DCB parameters, but you have to get this entry 
name and library information to the control program. The expansion of the LINK macro 
instruction does this by creating a control program parameter list (the information required by 
the control program) and passing its address to the control program. After the control program 
finds the entry name, it places the address in register 15. 

The return address in your control section is always the instruction following the LINK; that is 
not, however, the address that the called load module receives in register 14. The control 
program saves the address of the location in your program in its own save area, and places in 
register 14 the address of a routine within the control program that will receive control. 
Because control was passed using the control program, return must also be made using the 
control program. The control program also handles all switching of addressing mode when 
processing the LINK macro instruction. 

The control program estabUshes a use count for a load module when control is passed using the 
LINK macro instruction. This is a separate use count from the count established for LOAD 
macro instructions, but it is used in the same manner. The count is increased by one when a 
LINK macro instruction is issued and decreased by one when return is made to the control 
program or when the called load module issues an XCTL macro instruction. 

Figure 22 and Figure 23 show the coding of a LINK macro instruction used to pass control to 
an entry point in a load module. In Figure 22, the load module is from the link, job, or step 
Hbrary; in Figure 23, the module is from a private library. Except for the method used to pass 
control, this example is similar to Figures 10 and 11. A problem program parameter list 
containing the addresses INDCB, OUTDCB, and AREA is passed to the called load module; 
the return point is the instruction following the LINK macro instruction. A V-type address 
constant is not generated, because the load module containing the entry point NEXT is not to 
be edited into the calling load module. Note that the EP parameter is chosen, since the search 
begins with the job pack area and the appropriate library as shown in Figure 19. 



LINK EP=NEXT , PARAM= ( INDCB , OUTDCB , AREA ) , VL=1 
RETURNPT ... 
AREA DC 12F'0' 



Figure 22. Use of the LINK Macro Instruction With the Job or Link Library 
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OPEN (PVTLIB) 



LINK EP=NEXT , DCB=PVTLIB , PARAM= ( INDCB , OUTDCB , 
AREA) ,VL=1 



PVTLIB DCB DDNAME=PVTLIBDD,DSORG=PO,MACRF=(R) 



Figure 23. Use of the LINK Macro Instruction With a Private Library 

Figure 24 and Figure 25 show the use of the BLDL and LINK macro instructions to pass 
control. Assuming that control is to be passed to an entry point in a load module from the link 
Ubrary, a BLDL macro instruction is issued to bring the directory entry for the member into 
virtual storage. (Remember, however, that time is saved only if more than one directory entry 
is requested in a BLDL macro instruction. Only one is requested here for simpUcity.) 



BLDL 0,LISTADDR 



DS OH 

LISTADDR DC H'Ol' 

DC H'60' 

NAMEADDR DC CL8 ' NEXT ' 

DS 26H 



List description field: 

Number of list entries 
Length of each entry 

Member name 

Area required for directory 
information 



Figure 24. Use of the BLDL Macro Instruction 

The first parameter of the BLDL macro instruction is a zero, which indicates that the directory 
entry is on the link, job, step, or task hbrary. The second parameter is the address in virtual 
storage of the Ust description field for the directory entry. The second two bytes at 
LISTADDR indicate the length of each entry. A character constant is established to contain 
the directory information to be placed there by the control program as a result of the BLDL 
macro instruction. The LINK macro instruction in Figure 25 can now be written. Note that 
the DE parameter refers to the name field, not the list description field, of the directory entry. 



LINK DE=NAMEADDR,DCB=0,PARAM=( INDCB, OUTDCB, AREA) ,VL=1 



Figure 25. The LINK Macro Instruction With a D£ Parameter 
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Using CALL or Branch and Link 

You can save time by passing control to a load module without using the control program. 
Passing control without using the control program is performed as follows. Issue a LOAD 
macro instruction to obtain a copy of the load module, preceded by a BLDL macro instruction 
if you can shorten the search time by using it. The control program returns the address of the 
entry point and the addressing mode in register 0 and the length in doublewords in register 1. 
Load this address into register 15. The linkage requirements are the same when passing control 
between load modules as when passing control between control sections in the same load 
module: register 13 must contain a save area address, register 14 must contain the return 
address, and register 1 is used to pass parameters in a parameter list. A branch instruction, a 
branch and link instruction, a branch and save instruction, a branch and save and set mode 
instruction (BASSM), or a CALL macro instruction can be used to pass control, using register 
15. Use BASSM only if there is to be an addressing mode switch. The return will be made 
directly to your program. 

Notes: 

1. You must use a branch and save and set mode instruction if passing control to a module in a 
different addressing mode. 

2. When control is passed to a load module without using the control program, you must check 
the load module attributes and current status of the copy yourself and you must check the 
status in all succeeding uses of that load module during the job step, even when the control 
program is used to pass control. 

The reason you have to keep track of the usabiUty of the load module has been discussed 
previously; you are not allowing the control program to determine whether you can use a 
particular copy of the load module. The following paragraphs discuss your responsibilities 
when using load modules with various attributes. You must always know what the reusability 
attribute of the load module is. If you do not know, you should not attempt to pass control 
yourself. 

If the load module is reenterable, one copy of the load module is all that is ever required for a 
job step. You do not have to determine the status of the copy; it can always be used. You can 
pass control by using a CALL macro instruction, a branch, a branch and link instruction, a 
branch and save instruction, or a branch and save and set mode instruction (BASSM). Use 
BASSM only if there is to be an addressing mode switch. 

If the load module is serially reusable, one use of the copy must be completed before the next 
use begins. If your job step consists of only one task, preventing simultaneous use of the same 
copy involves making sure that the logic of your program does not require a second use of the 
same load module before completion of the first use. An exit routine must not require the use 
of a serially reusable load module also required in the main program. 

Preventing simultaneous use of the same copy when you have more than one task in the job 
step requires more effort on your part. You must still be sure that the logic of the program for 
each task does not require a second use of the same load module before completion of the first 
use. You must also be sure that no more than one task requires the use of the same copy of the 
load module at one time; the ENQ macro instruction can be used for this purpose. Properly 
used, the ENQ macro instruction prevents the use of a serially reusable resource, in this case a 
load module, by more than one task at a time. Refer to "Resource Control" for a complete 
discussion of the ENQ macro instruction. A conditional ENQ macro instruction can also be 
used to check for simultaneous use of a serially reusable resource within one task. 
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If the load module is nonreusable, each copy can only be used once; you must be sure that you 
use a new copy each time you require the load module. You can ensure that you always get a 
new copy by using a LINK macro instruction or by doing as follows: 

1. Issue a LOAD macro instruction before you pass control. 

2. Pass control using a branch, branch and link, branch and save, branch and save and set 
mode instruction, or a CALL macro instruction. 

3. Issue a DELETE macro instruction as soon as you are through with the copy. 

How Control is Returned 

The return of control between load modules is the same as return of control between two 
control sections in the same load module. The program in the load module returning control is 
responsible for restoring registers 2-14, possibly loading a return code in register 15, passing 
control using the address in register 14 and possibly setting the correct addressing mode. The 
program in the load module to which control is returned can expect registers 2-13 to be 
unchanged, register 14 to contain the return address, and optionally, register 15 to contain a 
return code. Control can be returned using a branch instruction, a branch and set mode 
instruction or the RETURN macro instrucLlon. If control was passed without using the control 
program, control returns directly to the calling program. However, if control was originally 
passed using the control program, control returns first to the control program, then to the 
calling program. 

The action taken by the control program is as follows. The control program returns in the 
caller's addressing mode. When control was passed using a LINK or ATTACH macro 
instruction, the responsibiUty coimt was increased by one for the copy of the load module to 
which control was passed to ensure that the copy would be in virtual storage as long as it was 
required. The return of control indicates to the control program that this use of the copy is 
completed, and so the responsibiUty count is decreased by one. The virtual storage area 
containing the copy is made available when the responsibility count reaches zero. 

Passing Control without Return 

The XCTL macro instruction is used to pass control between load modules when no return of 
control is required. You can also pass control using a branch instruction; however, when you 
pass control in this manner, you must protect against multiple uses of nonreusable or serially 
reusable modules. The following paragraphs discuss the requirements for passing control 
without return in each case. 

Passing Control Using a Branch Instruction 

The same requirements and procedures for protecting against reuse of a nonreusable copy of a 
load module apply when passing control without return as were stated under "Passing Control 
With Return." The procedures for passing control are as follows. 

A LOAD macro instruction should be issued to obtain a copy of the load module. The entry 
address and addressing mode returned in register 0 are loaded into register 15. The linkage 
requirements are the same when passing control between load modules as when passing control 
between control sections in the same load module; register 13 must be reloaded with the old 
save area address, then registers 14 and 2-12 restored from that old save area. Register 1 is 
used to pass parameters in a parameter list. If the addressing mode does not change, a branch 
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instruction is issued to pass control to the address in register 15; if the addressing mode does 
change, a branch and save and set mode macro instruction is used. 

Note: Mixing branch instructions and XCTL macro instructions is hazardous. The next topic 
explains why. 

Using the XCTL Macro Instraction 

The XCTL macro instruction, in addition to being used to pass control, is used to indicate to 
the control program that this use of the load module containing the XCTL macro instruction is 
completed. Because control is not to be returned, the address of the old save area must be 
reloaded into register 13. The return address must be loaded into register 14 from the old save 
area, as must the contents of registers 2-12. The XCTL macro instruction can be written to 
request the loading of registers 2-12, or you can do it yourself. If you restore all registers 
yourself, do not use the EP parameter. This creates an inline parameter list that can only be 
addressed using your base register, and your base register is no longer valid. If EP is used, you 
must have XCTL restore the base register for you. 

When using the XCTL macro instruction, you pass parameters in a parameter list. In this case, 
however, the parameter list (or the parameter data) must be estabUshed in a portion of virtual 
storage outside the current load module containing the XCTL macro instruction. This is 
because the copy of the current load module may be deleted before the called load module can 
use the parameters, as explained in more detail below. 

The XCTL macro instruction is similar to the LINK macro instruction in the method used to 
pass control: control is passed by way of the control program using a control program 
parameter list. The control program loads a copy of the load module, if necessary, loads the 
entry address in register 15, saves the address passed in register 14, and passes control to the 
address in register 15. The control program adds one to tiie responsibility count for the copy of 
the load module to which control is to be passed and subtracts one from the responsibility 
count for the current load module. The current load module in this case is the load module last 
given control using the control program in the performance of the active task. If you have been 
passing control between load modules without using the control program, chances are the 
responsibility count will be lowered for the wrong load module copy. And remember, when the 
responsibility count of a copy reaches zero, that copy may be deleted, causing unpredictable 
results if you try to return control to it. 

Figure 26 shows how this could happen. Control is given to load module A, which passes 
control to the load module B (step 1) using a LOAD macro instruction and a branch and link 
instruction. Register 14 at this time contains the address of the instruction following the branch 
and link. Load module B then is executed, independently of how control was passed, and issues 
an XCTL macro instruction when it is finished (step 2) to pass control to load module C. The 
control program knowing only of load module A, lowers the responsibility count of A by one, 
resulting in its deletion. Load module C is executed and returns to the address which used to 
follow the branch and hnk instruction. Step 3 of Figure 26 indicates the result. 

Two methods are available for ensuring that the proper responsibility count is lowered. One 
way is to always use the control program to pass control with or without return. The other 
method is to use only LOAD and DELETE macro instructions to determine whether or not a 
copy of a load module should remain in virtual storage. 
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Figure 26. Misusing Control Program Facilities Causes Unpredictable Results 
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Additional Entry Points 



Through the use of linkage editor facilities you can specify as many as 17 different names (a 
member name and 16 aliases) and associated entry points within a load module. It is only 
through the use of the member name or the aliases that a copy of the load module can be 
brought into virtual storage. Once a copy has been brought into virtual storage, however, 
additional entry points can be provided for the load module, subject to one restriction. The 
load module copy to which the entry point is to be added must be one of the following: 

• A copy that satisfied the requirement of a LOAD macro instruction issued during the same 
task 

• The copy of the load module most recently given control through the control program in 
performance of the same task 

The entry point is added through the use of the IDENTIFY macro instruction, which can be 
issued only by a program running under a program request block (PRB). The IDENTIFY 
macro instruction cannot be issued by supervisor call routines or asynchronous exit routines 
established using other supervisor macro instructions. 

When you use the IDENTIFY macro instruction, you specify the name to be used to identify 
the entry point, and the virtual storage address of the entry point in the copy of the load 
module. The address must be within a copy of a load module that meets the requirements 
listed above; if it is not, the entry point will not be added, and you will be given a return code 
of OC (hexadecimal). The name can be any valid sjnnbol of up to eight characters, and does 
not have to correspond to a name or symbol within the load module. The name must not be 
the same as any other name used to identify any load module available to the control program; 
duplicate names cause errors. The control program checks the names of all load modules in the 
link pack area, and the job pack area when you issue an IDENTIFY macro instruction, and 
provides a return code of 8 if a duplicate is found. You are responsible for not duplicating a 
member name or an ahas in any of the libraries. 

IDENTIFY services sets the addressing mode of the alias entry point equal to the addressing 
mode of the major entry point. 

If an authorized caller creates an ahas for a module in the pageable Hnk pack area, IDENTIFY 
services places an entry for the aUas on the active link pack area queue. If an unauthorized 
caller creates an ahas for a module in the pageable link pack area, IDENTIFY services places 
an entry for the alias on the task's job pack queue. 



Entry Point and Calling Sequence Identifiers as Debugging Aids 

An entry point identifier is a character string of up to 70 characters that can be specified in a 
SAVE macro instruction. The character string is created as part of the SAVE macro 
instruction "expansion. 

A caUing sequence identifier is a 16-bit binary number that can be specified in a CALL or a 
LINK macro instruction. When coded in a CALL or a LINK macro instruction, the calUng 
sequence identifier is located in the two low-order bytes of the fullword at the return address. 
The high-order two bytes of the fullword form a NOP instruction. 
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Resource Control 



Task Synchronization 

Some planning on your part is required to determine what portions of one task are dependent 
on the completion of portions of all other tasks. The POST macro instruction is used to signal 
completion of an event; the WAIT and EVENTS macro instructions are used to indicate that a 
task cannot proceed until one or more events have occurred. An event control block is used 
with the WAIT, EVENTS or POST macro instructions; it is a fuUword on a fuUword boundary, 
as shown in Figure 27. 



An event control block is also used when the ECB parameter is coded in an ATTACH macro 
instruction. In this case the control program issues the POST macro instruction for the event 
(subtask termination). Either the 24-bit (bits 8 to 31) return code in register 15 (if the task 
completed normally) or the completion code specified in the ABEND macro instruction (if the 
task was abnormally terminated) is placed in the event control block as shown in Figure 27. 
The originating task can issue a WAIT or EVENTS WAIT = YES macro instruction specifying 
the event control block; the task will not regain control until after the event has taken place and 
the event control block is posted (except if an asynchronous event occurs, for example, timer 
expiration). 

0 12 31 



W 



completion code 



Figure 27. Event Control Block 



When an event control block is originally created, bits 0 (wait bit) and 1 (post bit) must be set 
to zero. If an ECB is reused, bits 0 and 1 must be set to zero before a WAIT, EVENTS ECB = 
or POST macro instruction can be specified. If, however, the bits are set to zero before the 
ECB has been posted, any task waiting for that ECB to be posted will remain in the wait state. 
When a WAIT macro instruction is issued, bit 0 of the associated event control block is set to 
1. When a POST macro instruction is issued, bit 1 of the associated event control block is set 
to 1 and bit 0 is set to 0. For an EVENTS type ECB, POST also puts the completed ECB 
address in the EVENTS table. 



A WAIT macro instruction can specify more than one event by specifying more than one event 
control block. (Only one WAIT macro instruction can refer to a event control block at a time, 
however.) If more than one event control block is specified in a WAIT macro instruction, the 
WAIT macro instruction can also specify that all or only some of the events must occur before 
the task is taken out of the wait condition. When a sufficient number of events have taken 
place (event control blocks have been posted) to satisfy the number of events indicated in the 
WAIT macro instruction, the task is taken out of the wait condition. 
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An optional parameter, LONG = YES or NO, allows you to indicate whether the task is 
entering a long wait or a regular wait. A long wait should never be considered for I/O activity. 
However, you might want to use a long wait when waiting for an operator response to a 
WTOR macro instruction. 



Using a Serially Reusable Resource 

When one or more programs using a serially reusable resource modify the resource, they must 
not use the resource simultaneously with other programs. Consider a data area in virtual 
storage that is being used by programs associated with several tasks of a job step. Some of the 
programs are only reading records in the data area; because they are not updating the records, 
they can access the data area simultaneously. Other programs using the data area, however, are 
reading, updating, and replacing records in the data area. Each of these programs must serially 
acquire, update, and replace records by locking out other programs. In addition, none of the 
programs that are only reading the records want to use a record that another program is 
updating until after the record has been replaced. 

If your program uses a serially reusable resource, you must prevent incorrect use of the 
resource. You must ensure that the logic of your program does not require the second use of 
the resource before completion of the first use. Be especially careful when using a serially 
reusable resource in an exit routine; because exit routines get control asynchronously with 
respect to your program logic, the exit routine could obtain a resource already in use by the 
main program. When more than one task is involved, using the ENQ macro instruction 
correctly can prevent simultaneous use of a serially reusable resource. 

The ENQ macro Instruction requests that the control program assign control of a resource to 
the active task. The control program determines the status of the resource, and does one of the 
following: 

• If the resource is available, the control program grants the request by returning control to 
the active task. 

• If the resource has been assigned to another task, the control program delays assignment of 
control by placing the active task in a wait condition until the resource becomes available. 

• Passes back a return code indicating the status of the resource. 

• Abends the caller on unconditional requests that would otherwise result in a non-zero 
return code. 

When the status of the resource changes so that the waiting task can get control, the task is 
taken out of the wait condition and placed in the ready condition. 

The DEQ macro instruction is used in conjunction with the ENQ macro instruction. If used 
properly, ENQ/DEQ can protect serially reusable resources. The rules for proper use of 
ENQ/DEQ are as follows: 

• Everyone must use ENQ/DEQ. 

• Everyone must use the same names and scope values for the same resources. 

• Everyone must use consistent ENQ/DEQ protocol. 
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Naming the Resource 



Represent the resource in the ENQ macro instruction by two names known as the qname and 
the mame, and by a scope indicator. The qname and mame need not have any relation to the 
actual name of the resource. The control program does not associate the name with the actual 
resource; it merely processes requests having the same qname, mame, and scope on a first-in, 
first-out basis. It is up to you to associate the names with the actual resource by ensuring that 
all users of the resource use qname, mame, and scope to represent the same resource. The 
control program treats requests having different qname, mame, and scope combinations as 
requests for different resources. Because the control program cannot determine the real name 
of the resource from the qname, mame, and scope, a task could use the resource by specifying a 
different qname, mame, and scope combination or by accessing the resource without using 
ENQ. In this case, the control program cannot provide any protection. 

I You will be abnormally terminated if you use SYSZ as the first four characters of a qname 

I (unless you are authorized, in key 0, or in supervisor state) because the control program uses 

1 SYSZ for its qnames. Avoid using SYSA through SYSY because the control program 

I sometimes uses these characters for its qnames as well. Either check with your system 

I programmer to see which of the SYSA through SYSY combinations you can use or avoid using 

I SYSx (where x is alphabetic) to begin qnames. 

You can request a scope of STEP, SYSTEM, or SYSTEMS. 

Use a scope of STEP if the resource is used only in your address space. The control program 
uses the address space identifier to make your resource unique in case someone else in another 
address space uses the same qname and mame and a scope of STEP, 

Use a scope of SYSTEM if the resource is available to more than one address space in the 
system. All programs that serialize on the resource must use the same qname and mame and a 

I scope of SYSTEM. For example, to prevent two jobs from using a named resource 

I simultaneously, use SYSTEM. 

Use a scope of SYSTEMS if the resource is available to more than one system. All programs 

that serialize on the resource must use the same qname and mame and a scope of SYSTEMS. 
I For example, to prevent two processors from using a named resource simultaneously, use 

I SYSTEMS. Note that the control program considers a resource with a SYSTEMS scope to be 

different from a resource represented by the same qname and rnkme but with a scope of STEP 

or SYSTEM. 

Types of Resources that Can Be Shared 

Global resource serialization, which handles ENQs, DEQs, and RESERVES, recognizes two 
types of resources. These are local resources and global resources. 

A local resource is a resource identified on the ENQ or DEQ macro instruction by a scope of 
STEP or SYSTEM. (Note that a resource with a scope of SYSTEM has its scope converted to 
SYSTEMS if the resource appears in the SYSTEM inclusion resource name list. See Planning: 
Global Resource Serialization for information about resource name Usts.) A local resource is 
recognized and serialized only within the requesting operating system. The local resource 
queues are updated to reflect each request for a local resource. If a system is not operating 
under global resource seriaUzation (that is, the system is not part of a global resource 
serialization complex), all resources requested are treated as local resources, and a resource 
requested by a RESERVE macro instruction always causes a hardware reserve for the entire 
volume. 
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If a system is part of a global resource serialization complex, a global resom-ce is identified on 
the ENQ or DEQ macro instruction by a scope of SYSTEMS. (Note that a resource with a 
scope of SYSTEMS has its scope changed to SYSTEM if the resource appears in the 
SYSTEMS exclusion resource name Ust.) A global resource is recognized and serialized by all 
systems in the global resource serialization complex. 

Requesting Exclusive or Shared Control 

To request exclusive control of the resource, code E in the ENQ macro instruction. If you are 
changing the resource, you must request exclusive control. 

To request shared control of the resource, code S in the ENQ macro instruction. Request 
shared control only if you are not changing the resource. 

Limiting Concurrent Requests for Resources 

In order to prevent any one job, started task, or TSO user from generating too many 
concurrent requests for resources, global resource serialization counts and limits the number of 
ENQs in each address space. When a user issues an ENQ, global resource serialization 
increases the count of outstanding requests for that address space by one and decreases the 
count by one when the user issues a DEQ. 

When the computed count reaches the threshold value or limit, global resource serialization 
processes subsequent requests as follows: 

• Unconditional requests (ENQs that use the RET = NONE option) are abended with a 
system code of X'538'. 

• Conditional requests (ENQs that specify the RET = HAVE or RET = USE option) are 
rejected and the user receives a return code of X'18'. 

The RESERVE and GQSCAN macros, which also increase the count of outstanding requests, 
are described in SPL: System Macros and Facilities. 

Processing the Request 

The control program constructs a unique list for each qname, rname, and scope combination it 
receives in an ENQ or RESERVE macro instruction. When a task makes a request by issuing 
an ENQ or RESERVE macro instruction, the control program searches the existing lists for a 
matching qname, rname, and scope. If it finds a match, the control program adds the task's 
request to the end of the existing list; the Ust is not ordered by the priority of the tasks on it. If 
the control program does not find a match, it creates a new list, and adds the task's request as 
the first (and only) element. The task gets control of the resource based on the following: 

• The position of the task's request on the list 

• Whether or not the request was for exclusive or shared control 

Figure 28 shows the status of a list built for a qname, rname, and scope combination. The S 
or E next to the entry indicates that the request was for either shared or exclusive control. The 
task represented by the first entry on the li§t always gets control of the resource, so the task 
represented by ENTRYl (Figure 28, Step 1) is assigned the resource. The request that 
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established ENTRY2 was for exclusive control, so the corresponding task is placed in the wait 
condition, along with the tasks represented by all the other entries in the Ust. 



ENTRYl (S) 
ENTRY2 (E) 
ENTRY3 (S) 
ENTRY4 (S) 
ENTRY5 (E) 
ENTRY6 (S) 

Step 1 



ENTRY2 (E) 
ENTRY3 (S)~ 
ENTRY4 (S) 
ENTRY5 (E) 
ENTRY6 (S) 

Step 2 



ENTRY3 (S) 
ENTRY4 (S) 
ENTRY5 (E) 
ENTRY6 (S) 

Step 3 



Figure 28. ENQ Macro Instruction Processing 

Eventually, the task represented by ENTRYl releases control of the resource, and the ENTRYl 
is removed from the list. As shown in Figure 28, Step 2, ENTRY2 is now first on the list, and 
the corresponding task is assigned control of the resource. Because the request that estabhshed 
ENTRY2 was for exclusive control, the tasks represented by all the other entries in the list 
remain in the wait condition. 



Figure 28, Step 3, shows the status of the list after the task represented by ENTRY2 releases 
the resource. Because ENTRY3 is now at the top of the Ust, the task represented by ENTRY3 
gets control of the resource. ENTRY3 indicates that the resource can be shared, and, because 
ENTRY4 also indicates that the resource can be shared, ENTRY4 also gets control of the 
resource. In this case, the task represented by ENTRY5 does not get control of the resource 
until the tasks represented by ENTRY3 and ENTRY4 release control because ENTRY5 
indicates exclusive use. 

The control program uses the following general rules in manipulating the lists: 



• The task represented by the first entry in the list always gets control of the resource. 

• If the request is for exclusive control, the task is not given control of the resource until its 
request is the first entry in the Ust. 

• If the request is for shared control, the task is given control either when its request is first 
in the Ust or when aU the entries before it in the Ust also indicate a shared request. 

• If the request is for several resources, the task is given control when all of the entries 
requesting exclusive control are first in their respective Usts and all the entries requesting 
shared control are either first in their respective Usts or are preceded only by entries 
requesting shared control. 



Duplicate Requests for a Resource 

A dupUcate request occurs when a task issues an ENQ macro instruction to request a resource 
that the task already controls. For example, if a task that has control of a resource issues an 
unconditional ENQ macro to request the same resource, the task is abnormally terminated. If 
you make a dupUcate request for a resource you might be abnormally terminated. With the 
second request, the control program recognizes the contradiction and returns control to the task 
with a non-zero return code or abnormally terminates the task. You should design your 
program to ensure that a second request for a resource made by the same task is never issued 
until control of the resource is released for the first use. Be especially careful when 
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using an ENQ macro instruction in an exit routine. Two specific reasons why the use of ENQ 
in an exit routine must be carefully planned are: 

• The exit may be entered more than once for the same TCB. 

• An exit routine may request resources already obtained by some other process associated 
with the TCB. 

More information on this topic follows under "Conditional and Unconditional Requests." 
Releasing the Resource 



Use the DEQ macro instruction to release a serially reusable resource that you obtained by 
using an ENQ macro instruction. If you try to release a resource for which you do not have 
control, you either get a non-zero return code or you are abnormally terminated. It is possible 
for many tasks to be placed in the wait condition while one task is assigned control of the 
resource. Having many tasks in the wait state might reduce the amount of work being done by 
the system, therefore, you should issue a DEQ macro instruction as soon as possible to release 
the resource, so that other tasks can use it. If a task terminates without releasing a resource, 
the control program releases the resource automatically. 



Conditional and Unconditional Requests 



Up to this point, only unconditional requests have been considered. You can, however, use the 
ENQ and DEQ macro instructions to make conditional requests by using the RET parameter. 
For authorized programs, the ECB parameter is another way to make conditional requests with 
the ENQ macro instruction. This parameter, restricted to APF-authorized (key 0 or supervisor 
state) programs, is described in SPL: System Macros and Facilities, Volume 2. One reason for 
making a conditional request is to avoid the abnormal termination that occurs if you issue two 
ENQ macro instructions for the same resource within the same task or when a DEQ macro 
instruction is issued for a resource for which you do not have control. 

The RET = parameter of ENQ and DEQ can provide the following options: 

RET=CHNG indicates the status of the resource specified is changed from shared to exclusive control. 

RET = HAVE indicates that control of the resource is requested conditionally; that is, control is requested only if a 
request has not been made previously for Uie same task. 

RET = TEST indicates the availability of the resource is to be tested, but control of the resource is not requested. 

RET = USE indicates control of the resource is to be assigned to the active task only if the resource is immediately 
available. If any of the resources are not available, the active task is not placed in a wait condition. 

For the following descriptions, the term "active task" mean the task issuing the ENQ macro 
instruction. No reference is intended to different tasks which might be active in other 
processors of a multiprocessor. 
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RET = TEST is used by a task to test the status of the corresponding qname, rname, and scope 
combination, without changing the Ust in any way or waiting for the resource. 

• A return code of 0 indicates that the active task does not now have control of the resource, 
but could have been given immediate control if it had been requested, because no other task 
has control of the resource. 

• A return code of 4 indicates that another task has control of the resource, and the active 
task would have been placed in a wait condition if it had made an unconditional request. 

• A return code of 8 indicates that the active task already has control of the resource. 

• A return code of 14 indicates that the active task does not yet have control of the resource, 
but is in the list to be given control at a later time when other task(s) release the resource. 

Note: For return code 14 to occur, the restricted use of the ECB= parameter of the ENQ 
must have been used to make an entry on the list without placing the task in a wait 
condition. 

RET = TEST is most useful for determining if the task already has control of the resource. It is 
less useful for determining the status of the list and taking action based on that status. In the 
interval between the time the control program checks the status and the time your program 
checks the return code and issues another ENQ macro instruction, another task could have 
been made active, and the status of the Ust could have changed. 

RET — USE is used if you want your task to assigned control of the resource only if the 
resource is immediately available. If the resource is not immediately available, no entry will be 
made on the list and the task will not be made to wait. RET = USE is most useful when there 
is other processing that can be done without using the resource. For example, by issuing a 
preliminary ENQ with RET = USE in an interactive task, you can attempt to gain control of a 
needed resource without locking your terminal session. If the resource is not available, you can 
do other work rather than enter a long wait for the resource. 

• A return code of 0 indicates that the active task did not have control of the resource prior 
to issuing the ENQ, but now has been given control and the corresponding entry has been 
put in the list. 

• A return code of 4 indicates that the active task has not been given control of the resource, 
and an entry has not been made in the list, because another task already has control of the 
resource, 

• A return code of 8 indicates that the active task already has control of the resource. 

• A return code of 14 indicates that the active task does not yet have control of the resource, 
but is in the Ust to be given control at a later time when other task(s) release the resource. 

• A return code of 18 indicates that the Umit for the number of concurrent resource requests 
has been reached. The task does not have control of the resource unless some previous 
ENQ/RESERVE request caused the task to obtain control of the resource. 

For authorized programs, the ECB parameter is another way to make conditional requests 
with the ENQ macro instruction. This parameter, restricted to APF-authorized (key 0 or 
supervisor state) programs, is described in SPL: System Macros and Facilities, Volume 2. 
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RET = CHNG is used to change a previous request from shared to exclusive control. 



• A return code of 0 indicates that the active task now has exclusive control of the resource. 
Either exclusive control was already held, or shared control was converted to exclusive 
control as requested. 

• A return code of 4 indicates that the requested change in attribute cannot be honored, 
because the active task is currently sharing the resource with another task. 

• A return code of 8 indicates that the active task does not have an entry on the list for the 
specified resource. There is nothing to change. 

• A return code of 14 indicates that the active task does have an entry on the hst for the 
resource, but is not yet in control of the resource. No change is made. 

For authorized programs, the ECB parameter is another way to make conditional requests 
with the ENQ macro instruction. This parameter, restricted to APF-authorized (key 0 or 
supervisor state) programs, is described in SPL: System Macros and Facilities, Volume 2. 

RET == HAVE is used with both the ENQ and DEQ macro instructions to specify a conditional 
request for control of a resource (ENQ) when you do not know whether or not you have 
already requested control of that resource. RET = HAVE is used to release control (DEQ), 
with protection against abnormal termination of the active task, if an ENQ is duplicated or a 
DEQ is issued for a resource not held. If the resource is owned by another task, you will be 
put in a wait condition until the resource becomes available. 

RET = HAVE with ENQ can make the active task wait until the resource becomes available. 

• A return code of 0 indicates that the active task did not previously have an entry on the list 
or control of the resource, but has now been given control. 

• A return code of 8 indicates that the active task already has control of the resource and 
already has an entry on the list. (Without RET = HAVE, this situation would cause 
abnormal termination. With RET = HAVE, it is effectively a no-operation.) 

• A return code of 14 indicates that the active task has entry on the list for the resource, but 
is not yet in control of the resource. No change is made. 

For authorized programs, the ECB parameter is another way to make conditional requests 
with the ENQ macro instruction. This parameter, restricted to APF-authorized (key 0 or 
supervisor state) programs, is described in SPL: System M<icros and Facilities, Volume 2. 

For DEQ: 

• A return code of 0 indicates that the DEQ routine found an entry for the active task on the 
list for the specified resource, and has removed the entry. If the active task held control of 
the resource, this action relinquishes control. If the active task did not hold control of the 
resource (because the restricted ECB parameter had been used with ENQ, and control has 
not meanwhile become available), the DEQ routine simply removes the entry from the list 
without affecting control of the resource. 

• A return code of 4 indicates the resource has been requested for the task, but the task has 
not been assigned control. The task is not removed from the wait condition. (This return 
code could result if DEQ is issued within an exit routine which was given control because 
of an interruption). 
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• A return code of 8 indicates that the active task did not have an entry on the list for the 
specified resource. There was no entry to dequeue. 

If ENQ and DEQ are used in an asynchronous exit routine, code RET == HAVE to avoid 
possible abnormal termination. 

Avoiding Interlock 

An interlock condition happens when two tasks are waiting for each others' completion, but 
neither task can get the resource it needs to complete. Figure 29 shows an example of an 
interlock. Task A has exclusive access to resource M, and higher-priority task B has exclusive 
access to resource N. When task B requests exclusive access to resource M, B is placed in a 
wait state because task A has exclusive control of resource M. 

The interlock becomes complete when task A requests exclusive control of resource N. The 
same interlock would have occurred if task B issued a single request for multiple resources M 
and N prior to task A's second request. The interlock would not have occurred if both tasks 
had issued single requests for multiple resources. Other tasks requiring either of the resources 
are also in a wait condition because of the interlock, although in this case they did not 
contribute to the conditions that caused the interlock. 





Task A 




Task B 


ENQ 


(M, A, E, 8, SYSTEM) 


ENQ 
ENQ 


(N,B,E, 8, SYSTEM) 
(M, A, E, 8, SYSTEM) 


ENQ 


(N,B,E, 8, SYSTEM) 







Figure 29. Interlock Condition 



The above example involving two tasks and two resources is a simple example of an interlock. 
The example could be expanded to cover many tasks and many resources. It is imperative that 
you avoid interlock. The following procedures indicate some ways of preventing interlocks. 

• Do not request resources that you do not need immediately. If you can use the serially 
reusable resources one at a time, request them one at a time and release one before 
requesting the next. 

• Share resources as much as possible. If the requests in the lists shown in Figure 29 had 
been shared, there would have been no interlock. This does not mean you should share a 
resource that you will modify. It does mean that you should analyze your requirements for 
the resources carefully, and not request exclusive control when shared control is enough. 

• Use the ENQ macro instruction to request control of more than one resource at a time. 
The requesting program is placed in a wait condition until all of the requested resources are 
available. Those resources not being used by any other program immediately become 
exclusively available to the waiting program. For example, instead of coding the two ENQ 
macro instructions shown in Figure 30, you could code the one ENQ macro instruction 
shown in Figure 31. If all requests were made in this manner, the interlock shown in 
Figure 29 could not occur. All of the requests from one task would be processed before 
any of the requests from the second task. The DEQ macro instruction can release a 
resource as soon as it is no longer needed; resources requested in a multiple ENQ can be 
individually released through separate DEQ instructions. 
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ENQ ( NAME 1ADD,NAME2ADD,E, 8, SYSTEM) 
ENQ ( NAME 3ADD , NAME4ADD , E , 10 , SYSTEM ) 



Figure 30. Two Requests For Two Resources 



ENQ ( NAME lADD , NAME2 ADD , E , 8 , SYSTEM , NAME3ADD , NAME4ADD , E , 10 , SYSTEM) 



Figure 31. One Request For Two Resources 

• If the use of one resource always depends on the use of a second resource, then you can 
define the pair of resources as one resource in the ENQ and DEQ macro instructions. You 
can use this procedure for any number of resources that are always used in combination. 
However, the control program cannot protect these resources if they are also requested 
independently. Any requests must always be for the set of resources. 

• If there are many users of a group of resources and some of the users require control of a 
second resource while retaining control of the first resource, it is still possible to avoid 
interlocks. In this case, each user should request control of the resources in the same order. 
For instance, if resources A, B, and C are required by many tasks, the requests should 
always be made in the order of A, B, and C. An interlock situation will not develop, since 
requests for resource A will always precede requests for resource B. 



Resource Access Control Facility (RACF) 

The Resource Access Control Facility (RACF) provides software access control measures that 
can be used to enhance data security in a computing system. RACF can be used in addition to 
any present data security measures currently being used. 

RACF provides the ability to specify access authorities under which the resources (for example, 
DASD data sets, tape volimies, and DASD volumes) in the system are made available to the 
users of the system. 

When users, groups, and resources are defined to RACF, RACF builds and stores their 
descriptions in profiles on the RACF data set. The profiles will be used by RACF for 
RACHECK authorization checking. 

For more information on RACF, see Resource Access Control Facility (RACF): General 
Information Manual. 

RACHECK Macro Instruction 

RACHECK processing determines if a user is authorized to obtain use of a resource protected 
by RACF. When a user requests access to a RACF-protected resource, acceptance of the 
request is based upon the identity of the user and whether the user has been permitted sufficient 
access authority to the resource. 
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RACF performs system authorization checking when a resource manager that controls a 
RACF-protected resource issues the RACHECK macro instruction before allowing a user 
access to the resource. 

RACSTAT Macro Instruction 

RACSTAT processing determines if RACF is active and optionally determines if RACF 
protection is in effect for a given resource class. The macro can be used to determine if a 
resource class is defined to RACF. 

FRACHECK Macro Instruction 

FRACHECK processing determines if a user is authorized to obtain a RACF-protected 
resource. FRACHECK is a branch-entered service that performs authorization checking for 
RACF-protected resources whose profiles have been brought into main storage by the 
RACLIST routine. 



System Authorization Facility (SAF) 

The System Authorization Facility (SAF) provides a system interface that conditionally directs 
control to the Resource Access Control Facility (RACF), if RACF is present, and/or a 
user-supplied processing routine when receiving a request from a resource manager. SAF does 
not require any other program product as a prerequisite, but overall system security functions 
are greatly enhanced and complemented by the concurrent use of RACF. The key element in 
SAF is the MVS router. 

MVS Router 

SAF provides an installation with centralized control over system security processing by using a 
system service called the MVS router. The MVS router provides a focal point and a common 
system interface for all products providing resource control. The resource managing 
components and subsystems call the router as part of certain decision-making functions in their 
processing, such as access control checking and authorization-related checking. These functions 
are called "control points." This single SAF interface encourages the use of common control 
functions shared across products and across systems. 

The router is always present whether or not RACF is present. If RACF is available in the 
system, the router passes control to the RACF routine (ICHRFROO) that invokes the 
appropriate RACF function based on the parameter information and the RACF router table 
(ICHRFROl), which associates router invocations with RACF functions. The RACF router 
table is described in the SPL: Resource Access Control Facility (RACF). Before it calls the 
RACF routine, the router calls an optional, user-suppUed security processing exit if one has 
been installed. The MVS router exit is described in SPL: Supervisor. 

Control points that issue the RACROUTE macro instruction enter the MVS router in the same 
key and state as the RACROUTE issuer. Control points that continue to issue the RACF 
macro instructions go directly to RACF, bypassing the router. 
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MVS Router Parameter List 



The MVS router parameter list (mapped by macro ICHSAFP) is generated when the 
RACROUTE macro is issued and describes the security processing request by providing the 
request type. If the router installation exit exists, the router passes the parameter list to this 
exit. If RACF is active, the router uses the request type information to invoke the appropriate 
RACF function. 



Field Name 
SAFPRRET 
SAFPRREA 
SAFPPLN 

SAFPREQT 



Offset 

0(0) 

4(4) 

8(8) 

10(A) 

12(C) 



Length 

4 

4 

2 

2 

2 



Description 

Return code - Defines the RACF or installation exit return code. 
Reason code - Defines the RACF or installation exit reason code. 
Length - Defines the length of the SAFP parameter list. 
Reserved 

Request type - A binary halfword corresponding to the request type on the 
RACROUTE macro. The request type and the associate request numbers 
are listed below. 

AUTH (RACHECK) - 1 (01) 
FASTAUTH (FRACHECK) - 2 (02) 





14(E) 


2 


Reserved 


SAFPREQR 


16 (10) 


4 


Request n«ne address - Points to an 8-byte character field containing the 
control point name. 


SAFPSUBS 


20 (14) 


4 


Subs^tem name address - Points to an 8-byte character field containing 
the calling subsystem's name, version, and release level. 


SAFPWA 


24 (18) 


4 


SAF work area address - Points to a 512-byte work area for use by the 
MVS router and the RACF front end routine. 




28 (IC) 


4 


Reserved 




32 (20) 


4 


Reserved 


SAFPRACP 


36 (24) 


4 


Offeet - Contains the (signed) offset from the start of the MVS router 



parameter list to the RACF parameter list. 



RACROUTE Macro Instruction 

The RACROUTE macro instruction is the interface to the MVS router that provides a focal 
point and a common system interface for all products providing resource control. The MVS 
router first invokes an optional installation exit and then invokes RACF, if RACF is active and 
installed on the system. 

The RACROUTE macro accepts all vaUd parameters for the RACF macros (RACHECK and 
FRACHECK) and internally issues the appropriate RACF macro to generate a RACF 
parameter Ust. When the RACROUTE macro internally invokes the RACF macros, 
RACROUTE verifies that only valid parameters have been coded and then passes the 
parameters to the MVS router. Existing control points that invoke RACF processing via the 
supervisor call interface can continue to do so or can replace the RACF supervisor calls with 
the RACROUTE macro. 

See the RACROUTE macro in Part II for a description of the return codes. 
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Program Interruption, Recovery /Termination, and Dumping Services 



The supervisor offers many services to detect and process abnormal conditions during system 
execution. The hardware detects certain types of abnormal conditions (such as an attempt to 
execute an instruction with an invaUd operation code) and causes program interruptions to 
occur. The software detects other abnormal conditions (such as an attempt to open a data set 
that is not defined to the system, which causes the OPEN routine to request abnormal 
termination by issuing an ABEND macro instruction). 

You can write exit routines to handle specific types of interruptions and abnormal conditions. 
The supervisor initiates the recovery /termination process for your program either when you 
request it (for example, by issuing an ABEND macro instruction) or when MVS/XA detects a 
condition that will degrade the system or destroy data. 



Interruption Services 

Some conditions encountered in a program cause a program interruption. These conditions 
include incorrect parameters and parameter specifications, as well as exceptional results, and are 
known generally as program exceptions. You can disable the interruptions for certain 
exceptions (fixed point and decimal overflow, exponent underflow, and significance) by setting 
the corresponding bits in the program status word (PSW) to zero. 

When a task becomes active for the first time, all program interruptions that can be disabled 
are disabled, and the task uses a standard control program exit routine, included when the 
system was generated. This exit routine gets control when certain program interruptions occur; 
it issues an ABEND macro instruction specifying task abnormal termination and requesting a 
dump. 



Specifying User Exit Routines 

By issuing the SPIE or ESPIE macro instruction, you can specify your own exit routine to be 
given control for one or more types of program exceptions. If you issue an ESPIE macro 
instruction, you can also pass the address of a parameter Ust to the exit routine. When one of 
the specified program exceptions occurs in a problem program being executed in the 
performance of a task, the exit routine receives control in the key of the TCB (TCBPKF) and 
in the addressing mode in effect when the SPIE or ESPIE was issued. (If a SPIE macro 
instruction was issued, this is 24-bit addressing mode.) For other program interruptions, part of 
the control program, the recovery termination manager (RTM), gets control. If the SPIE or 
ESPIE macro instruction specifies an exception for which the interruption has been disabled, 
the control program enables the interruption when the macro instruction is issued. 
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The environment established by an ESPIE macro instruction exists for the entire task, until the 
environment is changed by another SPIE/ESPIE macro instruction, or until the program 
creating the ESPIE returns via an SVC 3. Each succeeding SPIE or ESPIE macro instruction 
completely overrides specifications in the previous SPIE or ESPIE macro instruction. You can 
intermix SPIE and ESPIE macro instructions in one program. Only one SPIE or ESPIE 
environment is active at a time. If an exit routine issues a SPIE or ESPIE macro instruction, 
the new SPIE/ESPIE environment does not take effect until the exit routine completes. 

The control program automatically deletes the SPIE/ESPIE exit routine when the RB that 
established the exit terminates. If a caller attempts to delete a specific SPIE/ESPIE 
environment established under a previous RB, the caller is abended with a system completion 
code of X'46D'. A caller can delete all previous SPIE and ESPIE environments (regardless of 
the RB under which they were established) by specifying a token of zero with the RESET 
option of the ESPIE macro instruction or an exit address of zero with the SPIE macro 
instruction. 

Notes: 

1. In MVSI370, the SPIE environment existed for the life of the task. In MVS/XA, the SPIE 
environment is deleted when the request block representing the program that issued the macro 
instruction is deleted. That is, when a program running under MVS/XA completes, any SPIE 
environments created by the program are deleted. This might create an incompatibility with 
MVS/SJO for programs that depend on the SPIE environment remaining in effect for the life 
of the task rather than the life of the request block. 

2. A SPIE exit routine established while executing in 24-bit addressing mode will not receive 
control if the program executing is in 31-bit addressing mode at the time of the interruption. 

Any problem program, executing in either 24-bit or 31 -bit addressing mode in the performance 
of a task, can issue the ESPIE macro instruction. If your program is executing in 31 -bit 
addressing mode, you cannot issue the SPIE macro instruction. The SPIE macro instruction is 
restricted in use to callers executing in 24-bit addressing mode in the performance of a task. 
The following topics describe how to use the SPIE and ESPIE macro instructions. 

Using the SPI£ Macro Instruction 

The PICA and the program interruption element (PIE) contain the information that enables the 
control program to intercept user-specified program interruptions established using the SPIE 
macro instruction. The PIE and its associated PICA are called the "SPIE environment." You 
can modify the contents of the active PICA in order to change the active SPIE environment. 
The PICA and the PIE are described in the following topics. 

Program Interruption Control Area 

The expansion of each standard or Ust form of the SPIE macro instruction contains a control 
program parameter list called the program interruption control area (PICA). The PICA, as 
shown in Figure 32, contains the new program mask for the interruption types that can be 
disabled in the PSW, the address of the exit routine to be given control when one of the 
specified interruptions occurs, and a code for interruption types (exceptions) specified in the 
SPIE macro instruction. 
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Displacement 

Bytes 0 1 2 3 4 5 



0000 Program 


Exit Routine Address 


Interruption Type 


Mask 







Figure 32. Program Interruption Control Area 

The control program maintains a pointer (in the PIE) to the PICA referred to by the last SPIE 
macro instruction executed. This PICA might have been created by the last SPIE or might 
have been created previously and referred to by the last SPIE. Before returning control to the 
calling program or passing control to another program via an XCTL macro instruction, each 
program that issues a SPIE macro instruction must cause the control program to adjust the 
SPIE environment to the condition that existed previously or to eliminate the SPIE environment 
if one did not exist on entry to the program. When you issue the standard or execute form of 
the SPIE macro instruction, the control program returns the address of the previous PICA in 
register 1. If no SPIE/ESPIE enviroimient existed when the program was entered, the control 
program returns zeroes in register 1. 

You can cancel the effect of the last SPIE macro instruction by issuing a SPIE macro 
instruction with no parameters. This action does not reestabUsh the effect of the previous 
SPIE; it does create a new PICA that contains zeroes, thus indicating that you do not want an 
exit routine to process interruptions. You can reestablish any previous SPIE environment, 
regardless of the number or type of subsequent SPIE macro instructions issued, by using the 
execute form of the SPIE specifying the PICA address that the control program returned in 
register 1. The PICA whose address you specify must still be valid (not overlaid). If you 
specify zeroes as the PICA address, the SPIE environment is eliminated. 

Figure 33 shows how to restore a previous PICA. The first SPIE macro instruction designates 
an exit routine called FDCUP that is to be given control if fixed-point overflow occurs. The 
address returned in register 1 is stored in the fullword called HOLD. At the end of the 
program, the execute form of the SPIE macro instruction is used to restore the previous PICA. 



SPIE FIXUP, (8) Provide exit routine for fixed-point 

overflow 

ST 1,H0LD Save address returned in register 1 



L 5, HOLD Reload returned address 

SPIE MF=(E,(5)) Use execute form and old PICA address 



HOLD DC F • 0 



Figure 33. Using the SPIE Macro Instruction 
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Program Interruption Element 



The first time you issue a SPIE macro instruction during the performance of a task, the control 
program creates a 32-byte program interruption element (PIE) in the virtual storage area 
assigned to your job step. Because the PIE is freed the first time you eliminate the SPIE 
envirormient (by specifying a PICA address of zero in the execute form of the SPIE macro 
instruction or by specifying a SPIE with no parameters), the control program also creates a 
PIE whenever you issue a SPIE macro instruction and no PIE exists. The format of the PIE is 
shown in Figure 34. 
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Figure 34. Program Interruption Element 



The PICA address in the PIE is the address of the program interruption control area used in 
the last execution of the SPIE macro instruction for the task. When control is passed to the 
routine indicated in the PICA, the BC mode old program status word contains the interruption 
code in bits 16-31 (the first byte is the exception extension code and the second is the exception 
code); you can test these bits to determine the cause of the program interruption. The control 
program stores the contents of registers 14,15,0,1, and 2 at the time of the interruption as 
indicated. 



Using the ESPIE Macro Instruction 

The ESPIE macro instruction extends the functions of the SPIE macro instruction to callers in 
31 -bit addressing mode. The options that you can specify using the ESPIE macro instruction 
are: 

• SET to estabUsh an ESPIE environment (that is, specify the interruptions for which the 
user-exit routine will receive control) 

• RESET to delete the current ESPIE environment and restore the SPIE/ESPIE environment 
specified 

• TEST to determine tiie active SPIE/ESPIE environment 

If you specify ESPIE SET, you pass the following information to the service routine: 

• A list of the program interruptions to be handled by the exit routine 

• The location of the exit routine 

• The location of a user-defined parameter hst 
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The service routine returns a token representing the previously active SPIE or ESPIE 
environment, or zero if there was none. 



If you code ESPIE RESET, you pass the token, which was returned when the ESPIE 
environment was established, back to the ESPIE service routine. The SPIE or ESPIE 
environment corresponding to the token is restored. If you pass a token of zero with RESET, 
all SPIE and ESPIE environments are deleted. 

If you specify ESPIE TEST, you will be able to determine the active SPIE or ESPIE 
environment. An active SPIE environment is represented by a pointer to the PICA, which 
resides in user storage. (The PICA is described earlier in this section.) The active ESPIE 
environment is represented by protected control blocks belonging to the ESPIE service. To 
change an active ESPIE environment, you must issue the ESPIE macro with the SET or 
RESET option. 

There are two control program areas associated with the ESPIE macro instruction. They are 
the extended program interruption element (EPIE) and the fake PICA. The EPIE and the fake 
PICA are described in the following topics. 

The Extended Program Interruption Element (EPIE) 

The control program creates an EPIE the first time you issue an ESPIE macro instruction 
during the performance of a task or whenever you issue an ESPIE macro instruction and no 
EPIE exists. The EPIE is freed when you eUminate the ESPIE environment. 



The EPIE contains the information that the ESPIE service routine passes to the ESPIE exit 
routine when it receives control. When the exit routine receives control, register 1 contains the 
address of the EPIE. (See the topic "Register Contents Upon Entry to User's Exit Routine" for 
the contents of the other registers.) The format of the EPIE is shown in Figure 35. 
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Figure 35. Extended Program Interruption Element 



The Fake PICA 

The fake PICA is used by MVS/XA to maintain compatibility between the SPIE and the ESPIE 
macro instructions. If you code a SPIE macro instruction to specify interruptions for which a 
SPIE exit routine is to receive control and if an ESPIE environment was previously active, the 
service routine returns the address of a fake PICA. The fake PICA resides in 24-bit addressable 
storage. The user should not modify its contents. 



Program Interruption, Recovery/Termination, and Dumping Services 57 



Register Contents Upon Entry to User's Exit Routine 



When control is passed to your routine, the register contents are as follows: 



Register 0: Internal control program information. 

Register!: Address of the PIE or EPIE for the task that caused the interruption. 

Registers 2-12: Same as when the program interruption occurred. 

Register 13: Address of the save area for the main program. The exit routine cannot use this area. 
Register 14: Return address (to the control program). 

Register IS: Address of the exit routine. The exit routine must be in virtual storage when it is required, and must 
return control to the control program using the address passed in register 14. For an ESPIE macro 
instruction, the control program restores all 16 registers from the EPIE. For a SPIE macro 
instruction, the control program restores registers 14,15,0,1, and 2 from the program interruption 
element after control is returned, but does not restore the contents of registers 3-13. If a program 
interruption occurs when the program interruption exit routine is in control, the control program exit 
routine gets control. 



Functions Performed in User Exit Routines 



Your exit recovery routine must determine the type of interruption that occurred before taking 
corrective action. Determining the type of interruption depends on whether the exit is 
associated with an ESPIE or a SPIE macro instruction. 

• For an ESPIE, your exit recovery routine can check the two-byte interruption code (the 
first byte is the exception extension code and the second is the exception code) at offset 
X'52' in the EPIE. 

• For a SPIE, your exit recovery routine can test bits 16 through 31 (the first byte is the 
exception extension code and the second is the exception code) of the old program status 
word (OPSW in BC mode) in the PIE. 

Note: For both ESPIE and SPIE - If you are using vector instructions and an exception of 8, 
12, 13, 14, or 15 occurs, your recovery routine can check the exception extension code (the first 
byte of the two-byte interruption code in the EPIE or PIE) to determine whether the exception 
was a vector or scalar type of exception. 

Your recovery routine can alter the contents of the registers when control is returned to the 
interrupted program. The procedure for altering the registers also depends on whether the exit 
is associated with an ESPIE or a SPIE. 



• For an ESPIE exit, the recovery routine can alter the contents of registers 0 through 15 in 
the save area in the EPIE because the control program reloads these registers from this area 
when it returns control to the interrupted program. 

• For a SPIE exit, the recovery routine can alter registers 14 through 2 in the register save 

area in the PIE because the control program reloads these registers from this area when it 
returns control to the interrupted program. To change registers 3 through 13, the recovery 
routine must alter the contents of the registers. 

The recovery routine can also alter the last four bytes of the OPSW in the PIE or EPIE. For 
an ESPIE, the recovery routine alters the CC and program mask starting at the third byte in 
the OPSW. By changing the OPSW, the routine can select any return point in the interrupted 
program. In addition, for ESPIE exits, the routine must set the AMODE bit of this four-byte 
address to indicate the addressing mode of the interrupted program. 
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Recovery /Termination Services 



Part of the control program, the recovery termination manager (RTM), monitors the flow of 
control of software recovery processing and supplies the services of normal and abnormal task 
termination. RTM selects the appropriate recovery or termination process according to the 
status of the system. 

RTM gets control in response to events such as the following: 

• Unanticipated program checks (except those protected by SPIE routines) 

• Machine checks 

• Invalid issuance of an SVC while locked, disabled, in SRB mode, or in cross memory 
mode^ or while an enabled, unlocked task mode FRR was established 

• I/O error on page-in request 

• Request by an authorized caller to terminate a task 

• ABEND macro instructions 

RTM invokes any recovery routine that has been established to recover or clean up for the 
process in control. The recovery routine could be one of yours or it could be a system routine. 
If this recovery routine cannot recover from the incident (it requests termination or itself fails), 
RTM invokes the previously-estabUshed recovery routine. This passing of control from one 
recovery routine to another is called percolation. If none of the recovery routines can recover 
(request a retry), the control program terminates the process in control. 

When a recovery routine gets control, it determines why it has been entered and decides either 
to percolate or to retry. To tell RTM what it wants done, the recovery routine issues the 
SETRP macro instruction, which manipulates fields in the system diagnostic work area 
(SDWA). When the recovery routine returns to RTM, RTM honors the request, if possible. 

To allow communication between the main routine and the recovery routine, there is a 
parameter area. For a recovery routine established by an ESTAE macro instruction, you can 
supply a parameter area by coding the PARAM parameter on the macro instruction. When 
you estabUsh a recovery routine, RTM saves a pointer to the parameter area and makes the 
pointer available to your recovery routine when it is entered. Usually, the main routine uses 
the parameter area to leave a footprint, that is, it sets indicators as part of normal processing; if 
an error occurs, these indicators let the recovery routine know where in the main process the 
failure occurred. The recovery routine can examine the footprint to determine what action to 
take. 

If the recovery routine decides that a retry might be successful, it asks RTM to continue 
execution of the main routine at some appropriate point. Note that retry is not always allowed. 
If a recovery routine requests a retry when retry is not allowed, RTM ignores the request and 
continues with the termination process (percolates). 

Any recovery routine that requests a retry must always include logic designed to avoid 
recursion, to prevent the creation of a tight loop between the recovery routine and the retry 
portion of the main routine. For example, if the recovery routine supplies a bad retry address 
to RTM, and the execution of the first instruction at the given address causes a program check, 
the first recovery routine to get control is the one that just requested the retry. If the recovery 
routine requests another retry at the same address, the loop is formed. 



1 



Cross memory mode is described in SPL: System Macros and Facilities. 
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Using S£TRP to Change the Completion and Reason Codes 



You can specify both completion and reason code values on the ABEND macro instruction, 
RTM passes these values to recovery exit routines to identify abnormal terminations. You can 
change the values of the completion code and the reason code by using the SETRP macro 
instruction. The COMPCOD keyword allows you to specify a new completion code; the 
REASON keyword allows you to specify a new reason code. 

The reason code has no meaning by itself, but must be used in conjunction with a completion 
code. In order to maintain meaningful completion and reason codes, RTM propagates changes 
to these values according to the following rules: 

• If a user changes both the completion code and the reason code, RTM accepts both new 
values. 

• If a user changes the reason code but not the completion code, RTM accepts the new 
reason code and uses the unchanged completion code. 

• If a user changes the completion code but not the reason code, RTM accepts the new 
completion code and uses a zero for the reason code. 

• If a user does not change either value, RTM uses the unchanged values. 

Changing the Completion and Reason Codes Directly 

Using the SETRP macro instruction is the preferred way for changing the completion and 
reason codes. If you change these values directly in a recovery exit routine you should emulate 
SETRP processing as follows: 

• When you change the completion code, store the new completion code in SDWACMPC, a 
three-byte field in the system diagnostic word area (SDWA), and set the one-bit flag, 
SDWACCF, to indicate the change. 

• When you change the reason code, store the new reason code in SDWACRC, a four-byte 
field in the SDWA, and set the one-bit flag, SDWAREAF, to indicate the change. 

Before passing control to a recovery exit routine, RTM saves the current completion and reason 
codes. After the recovery routine returns control to RTM, RTM examines the contents of the 
SDWACCF and SDWAREAF flags to determine whether changes have been made to the 
completion and 

reason codes and then determines which values to pass to the next recovery exit routine. RTM 
makes this decision as shown in the following table: 

SDWACCF SDWAREAF Values passed to the 

Completion code flag Reason code flag next recovery exit routine 

ON OFF The abend completion code and a reason code of zero 

OFF ON The unchanged completion code and the altered reason code 

ON ON The altered completion code and the altered reason code 

If both flags are off, RTM passes the values in the user's SDWA to the next recovery exit 
routine unless the completion code has been changed and the reason code has not been 
changed. In this case RTM passes the value of the completion code in the user's SDWA and a 
reason code of zero to the next recovery exit routine. 
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Handling ABENDs 



The control program does a great deal of checking for abnormal conditions. It uses hardware 
to detect errors such as protection violations or addressing errors. The data management and 
supervisor routines provide some error checking facilities to ensure that, based on the 
information you have provided, only valid data is being processed, and that you have not made 
any conflicting requests. For abnormal conditions that can possibly be corrected, the control 
program returns to your program with a return code indicating the probable source of the 
error. For conditions that indicate that further processing would result in degradation of the 
system or destruction of data, the control program gives control to RTM. 

There will, of course, be abnormal conditions unique to your program that the control program 
cannot detect. Figure 36 is an example of one of these. The routine shown in Figure 36 
checks a control field in an input parameter list to determine which fimction the program is to 
perform. Only characters 1 through 4 are valid in the control field. The presence of any other 
character is invaUd, but the routine must be prepared to detect and handle these characters. 
One way to handle an invalid character is to return to the calling program with an error return 
code. The calling program can then try to interpret the return code and recover from the error. 
If it cannot do so, the calling program can detach its incomplete subtasks, execute its usual 
termination procedures, and return control to its calling program, again with an error return 
code. This procedure might result in termination of all the tasks of a job step; if it does, you 
can use the COND parameters of the JOB and EXEC statements to indicate whether 
subsequent job steps should be executed. 

Another way to handle this unexpected condition is to issue an ABEND macro instruction. 
RTM gets control. 

The position within the job step hierarchy of the task for which the ABEND macro instruction 
is issued determines the exact function of the abnormal termination routine. If an ABEND 
macro instruction is issued when the job step task (the highest level or only task) is active, or if 
the STEP parameter is coded in an ABEND macro instruction issued during the performance 
of any task in the job step, all the tasks in the job step are terminated. For example, if the 
STEP parameter is coded in an ABEND macro under TSO, the TSO job will be terminated. 
An ABEND macro instruction (without a STEP parameter) that is issued in performance of 
any task in the job step task usually causes only that task and its subtasks to be abnormally 
terminated. However, if the abnormal termination cannot be fulfilled as requested, it might be 
necessary for RTM to abnormally terminate the job step task. 
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Figure 36. Detecting an Abnormal Condition 

If you have created a recovery routine for your program, RTM passes control to your routine. 
If you have not set up a recovery routine, RTM handles the problem. The action RTM takes 
depends on whether or not the job step is going to be terminated. 

If the job step is not going to be terminated, RTM: 

• Releases the resources owned by the terminating task and all of its subtasks starting with 
the lowest level task. 



Places the system or user completion code specified in the ABEND macro instruction in the 
task control block of the active task (the task for which the ABEND macro instruction was 
issued). 

Posts the ECB with the completion code specified in the ABEND macro instruction if the 
ECB parameter was coded in the ATTACH macro instruction issued to create the active 
task. 
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• Schedules the end-of-task exit routine to be given control when the originating task 
becomes active if the ETXR parameter was coded in the ATTACH macro instruction 
issued to create the active task. 

• Calls a routine to FREEMAIN the terminating TCB. 
If the job step is to be terminated, RTM: 

• Releases the resources owned by each task, starting with the lowest level task, for all tasks 
in the job step. No end-of-task exit routine is given control. 

• Writes the system or user completion code specified in the ABEND macro instruction on 
the system output device. 

The remaining steps in the job are skipped unless you can establish your own recovery routine 
to perform similar functions and any other functions that your program requires. Use either 
the ESTAE macro instruction or the ATTACH macro instruction with the ESTAI option to set 
up an error routine that gets control whenever your program issues an ABEND macro 
instruction. Your error routine also gets control if the system issues an ABEND on your 
behalf. Your routine can determine its actions with regard to the abnormal condition. With 
this approach, you can put less error handling code in your mainline routines. For example, 
there is no need to check return codes after a subroutine if the subroutine issues an ABEND. 
The error handling functions can be part of the ESTAE or ESTAI routines that execute only 
when there is an error. 

How to Use an ESTAE Recovery Routine 

Within an ESTAE recovery routine, you can perform pre-termination functions and diagnose 
the error. You can also determine whether abnormal termination should continue for the task, 
or whether normal processing can continue at some point in the mainline routine. 

When the abnormal termination is issued, the ESTAE recovery routine must be resident. It can 
either be part of the program issuing the ESTAE or be brought into virtual storage with the 
LOAD macro instruction. 

A single program can create more than one recovery routine by issuing the ESTAE macro 
instruction with the CT parameter. (The program can also overlay or cancel recovery routines 
by issuing ESTAE macros with the OV parameter or with an address of zero, respectively.) All 
ESTAE requests issued by programs running under the same task are queued so that the 
routine established by the most recent ESTAE request is the first to get control. If this routine 
fails or requests that abnormal termination continue (percolation), RTM cancels the routine 
and the exit established by the previous ESTAiE request gets control. 

If you want to use the same recovery routine for several tasks at the same time, the routine 
must be reenterable. For convenience, you should make all your ESTAE exit routines 
reenterable. 

You must cancel all the ESTAE routines you have created before returning control to your 
caller. If you try to cancel an ESTAE routine not associated with your request block, you get a 
return code that indicates your request is invaUd. 
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ProYiding Information for Dump Analysis and Elimination 

Dump analysis and elimination (DAE) uses information that callers provide in ESTAE recovery 
routines to construct unique symptom strings needed to describe software failures. DAE uses 
these symptom strings to analyze dumps and suppress dupUcates as requested. Each symptom 
string contains specific pieces of information called symptoms that DAE obtains from fields in 
the system diagnostic work area (SDWA), SDWA extensions, ABDUMP symptom area, and 
SDWA variable recording area (SDWAVRA). 

When using DAE, you must select symptoms carefully. If the data you supply is too precise, 
no other failure will have the same symptoms; if the data is too general, many failures will have 
the same symptoms. ; 

The following publications contain additional information pertaining to DAE: 

• SPL: System Modifications provides information about how an installation can modify 
DAE to fit its needs. 

• Operations: System Commands contains the syntax and use of the SET DAE command. 

• Debugging Handbook contains sample symptom output and DAE control block 

information. 

• System Logic Library provides a description of the logic and an explanation of symptom 
strings. 

• SPL: System Macros and Facilities Volume 1 describes the function of DAE for authorized 

users. 

Interface to an ESTAE Recovery Routine 

Before your first ESTAE recovery routine receives control, RTM performs I/O and 
asynchronous processing requests specified in the ESTAE macro instruction. RTM performs 
the requested I/O processing only for the first ESTAE routine. Subsequent routines receive an 
indication of the I/O processing previously done, but no additional processing is performed. 
However, RTM performs asynchronous processing for each routine. 

The recovery routine is enabled and has the same protection key and PSW key mask (PKM) as 

the routine that established the recovery routine as long as the establishing routine was under a 
problem program protection key (keys 8-15). An ESTAE routine created by a program running 
under key 0-7 gets control in key 0. 

Before each ESTAE recovery routine receives control, RTM tries to get storage for and to 
initialize a work area to contain information about the error. This work area is called the 
system diagnostic work area (SDWA). To access the SDWA, you must include the SDWA 
mapping macro - IHASDWA - as a DSECT in your ESTAE routine. Figure 37 shows key 
fields in the SDWA. 
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Field Name Use 

SDWAPARM This four-byte field, located at offset 0, contains the pointer to the user parameter list that you supply 
for an ESTAE-type recovery routine. 

SDWACMPC This three-byte field contains the ABEND completion code that existed when RTM gave control to 
the recovery routine. The recovery routine can change the ABEND code by changing this field. The 
system code appears in the first twelve bits and the user code appears in the second twelve bits. 

SDWAGRSV This field shows the contents of general registers 0-15 as they were at the time of the error. 

SDWACRC This four-byte field contains the reason code that existed when RTM entered the recovery routine. 
The recovery routine can change the reason code by changing this field. 

SDWAECl This field contains the PSW that existed at the time of the error. 

SDWAEC2 The contents of this field vary according to the type of recovery routine: 

• For an ESTAE routine, the field contains the extended control PSW of the RB that created the 
recovery routine at the time the RB last incurred an interruption. 

• For an ESTAI routine, this field contains zeroes. 
SDWASRSV The contents of this field vary according to the type of recovery routine. 

• For an ESTAE routine, this field contains the general registers 0-15 of the RB that established 
the recovery routine as they were at the time the RB last incurred an interruption. 

• For an ESTAI routine, this field contains zeroes. 

If the recovery routine requests a retry, RTM uses the contents of this field to load the registers for the 
retry routine. To change the contents of the registers for the retry routine, you must make the changes 
to this field and request a register update on the SETRP macro instruction. 

SDWASPID This field contains the subpool ID of the SDWA. 

SDWALNTH This field contains the length, in bytes, of the SDWA. 

SDWACOMU The recovery routines use this 8-byte field to communicate with each other when percolation occurs. 

RTM copies this field from one SDWA to the next on all percolations. If the field contains zeroes, 
either there was no information passed or RTM was not able to pass it. 

SDWAVRAL This field contains the length of the variable recording area (VRA) for this SDWA. 

SDWAHEX This is a one bit field set by the recovery routine to indicate that EREP is to print the data in the VRA 
in hexadecimal form. 

SDWAEBC This is a one-bit field set by the recovery routine to indicate that EREP is to print the data in the VRA 
in EBCDIC form. 

SDWAURAL This is a one-byte field set by the recovery routine to indicate the length of the VRA used. The field 
initially contains zeroes. Whenever the recovery routine uses any part of the VRA, it must set this 

field. 

SDWACCF The recovery routine sets this one-bit field when it changes the completion code. 

SDWAREAF The recovery routine sets this one-bit field when it changes the reason code. 

SDWAFAIN This 12-byte field contains the six bytes of the instruction stream that both precede and follow the 
failing instruction pointed to by the PSW. The SDWAFAIN field contains zeroes if RTM cannot 
access the failing instruction stream pointed to by the time-of-error PSW. For example, if the 
time-of-error PSW is not valid, the SDWAFAIN field contains zeroes. 

SDWADAET This eight-byte field contains DAE status and error flags for this dump. 

SDWAOCUR This two-byte field contains the current count of the number of previous occurrences of these 
symptoms in other SDWAs. 



Figure 37. Key Fields in tiie SDWA 
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The first field in the SDWA contains the address of the parameter Ust established by the 
ESTAE macro instruction. The register contents on entry to the EST AE routine depends on 
whether or not RTM obtained an SDWA. If RTM obtained an SDWA, the registers are as 

follows: 

Register 0 A code indicating tlie type of I/O processing performed: 

0 — Active I/O has been quiesced and is restorable. 

4 — Active I/O has been halted and is not restorable. 

8 — No I/O was active when the ABEND occurred. 

16 — No I/O processing was performed. 

Register 1 Address of the SDWA. 

Registers 2-12 Unpredictable. 

Register 13 Address of a 72-byte register save area. 

Register 14 Return address. 

Register IS Entry point address. 



When the ESTAE routine has completed its analysis of the error, it can use the SETRP macro 
instruction to inform RTM what it wants done. The SETRP macro instruction initializes the 
SDWA with the desired options. You can return from the ESTAE exit routine by using the 
SETRP REGS parameter or by using a BR 14 instruction. 



If RTM could not obtain an SDWA, the register contents are as follows: 

Register 0 12 (decimal). RTM could not obtain an SDWA. 

Register 1 ABEND completion code. 

Register 2 Address of the parameter list specified in the ESTAE macro instruction or 0. 

Registers 3-13 Unpredictable. 

Register 14 Return address. 

Register 15 Entry point address. 



If RTM could not provide an SDWA, it does not provide a register save area either. In this 
case, your ESTAE routine must save the address in register 14 and use it as the return address 
to RTM. You must place a return code in register 15 before returning to RTM. The return 
code indicates whether ABEND processing is to be continued for the task or whether a retry 
address can be given control. The return codes are: 

Return 

Code Meaning 

0 Continue with termination. Any ESTAE routines that were established prior to this routine will get control. 

4 Give control to the retry address. (You must place the retry address in register 0.) 

How to Use an ESTAI Routine 



You can provide an exit in your program to intercept abnormal termination of a subtask by 
using the ESTAI parameter on the ATTACH macro instruction you issue to create the subtask. 
Once you establish an ESTAI routine for one of your subtasks, it will be used for all of your 
subtasks. For example, suppose task A attaches task B and uses the ESTAI parameter in the 
ATTACH macro instruction. When task B attaches task C, the ESTAI routine created by task 
A is active for C as well as B. 



Because more then one subtask can abnormally terminate at the same time, the ESTAI routine 
might be used by more than one subtask concurrently. Your ESTAI exit routines must 
therefore be reenterable. 
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Interface to an ESTAI Routine 

ESTAI routines are entered after all ESTAE routines that exist for a given task have received 
control and have either failed or percolated. The interface to ESTAI routines is the same as for 
ESTAE exits, however, one additional option is available for ESTAI. When you return to 
RTM, you can specify return code 16 either on the SETRP macro instruction if an SDWA 
exists, or in register 15 if an SDWA is not available. The return code indicates to RTM that 
termination should continue and that no other ESTAI routines should receive control for that 
task. 

ESTAE/ESTAI Retry Routines 

If a given ESTAE or ESTAI routine requests percolation, RTM gives control to the next oldest 
ESTAE or ESTAI routine that exists for the task. However, if a given ESTAE or ESTAI exit 
routine requests retry, the control program takes a dump if requested and does not process any 
further ESTAE or ESTAI routines. 

An ESTAE or ESTAI routine can request retry whenever the SDWACLUP bit in the SDWA is 
set to zero. To request retry, the exit routine must supply a retry address. The retry address is 
the point in the mainline routine that is to get control in order to continue its processing. In 
response to a valid retry request, RTM gives control to the retry address suppUed. A retry 
routine requested by an ESTAE routine operates as an extension of the mainUne code. That is, 
the retry routine operates under the same RB that issued the request for ESTAE recovery. All 
RBs prior to the retry RB are purged before giving control to the retry routine. 

RTM purges the RB queue to cancel the effects of partially executed programs that are at a 
lower level in the program hierarchy than the program for which the retry occurs. Certain 
effects, however, cannot be canceled. Among these are: 

• Subtasks created by an RB to be purged 

• Resources allocated by the ENQ macro instruction 

• DCBs that exist in dynamically-acquired virtual storage 

If there are quiesced restorable I/O operations, the retry routine can restore them. RTM 
supplies a pointer to the purged I/O request Hst. You can use SVC RESTORE to have the 
control program restore all I/O requests on the list. The retry routine should free the storage 
occupied by the SDWA (if there was an SDWA) when that storage is no longer needed unless 
the exit routine specified FRESDWA=YES on the SETRP macro instruction. The subpool 
number and length to use on the FREEMAIN macro instruction are in the SDWA. 

Interface to a Retry Routine 

There are two different interfaces to a retry routine: 

• If RTM was able to obtain an SDWA, you can set the register contents in the SDWA to 
whatever you wish and request that they be passed to the retry routine by coding 
RETREGS=YES in the SETRP macro instruction. This method is used most often in 
mainline processing. 

• If RTM could not obtain an SDWA or if RETREGS = NO was specified on the SETRP 
macro instruction, only parameter registers are passed to the retry routine. This method is 
used most often if a special retry routine is to get control. 



Program Interruption, Recovery /Termination, and Dumping Services 67 



If RTM could not obtain an SDWA, register contents are as follows: 



Register 0 
Register 1 
Register 2 



12 (decimal) 

Address of the user parameter list established via the ESTAE macro instruction 

Address of the purge I/O restore list (PIRL) if I/O was quiesced and is restorable, otherwise 0 

Unpredictable 

Address of an SVC 3 instruction 
Entry point address of the retry routine 



Registers 3-13 



Register 14 
Register IS 



If RTM obtained an SDWA and the retry routine specified RETREGS = NO or 
FRESDWA=NO: 



Register 0 
Register 1 



0 

Address of the SDWA 
Unpredictable 

Address of an SVC 3 instruction 
Entry point address of the retry routine 



Registers 2-13 



Register 14 
Register 15 



If RTM obtained an SDWA and the retry routine specified RETREGS=NO and 
FRESDWA = YES: 



Register 0 
Register 1 
Register 2 



20 (decimal) 

Address of the user parameter list established via the ESTAE macro instruction 
Address of the PIRL if I/O was quiesced and is restorable, otherwise 0 
Unpredictable 

Address of an SVC 3 instruction 
Entry point address of the retry routine 



Registers 3-13 



Register 14 
Register 15 



If the retry routine requested register update (RETREGS = YES), the registers, as they appear 
in the SDWA, are passed to the retry routine. 

In all cases, the routine runs enabled and the protection key is the same key as the routine that 
established the retry routine. 



A problem program can request two types of storage dumps: 

• An ABEND dump obtained through use of the DUMP parameter in the ABEND macro 
instruction or the DUMP = YES parameter on the SETRP macro instruction in a recovery 



An ABEND macro instruction initiates error processing for a task. The DUMP option of 
ABEND requests a dump of storage and the DUMPOPT option may be used to specify the 
areas to be displayed. These dump options may be expanded by an ESTAE or EST AI routine. 
The control program usually requests a dump for you when it issues an ABEND macro 
instruction. However, the control program can provide an ABEND dump only if you include a 
DD statement (SYSABEND, SYSMDUMP, or SYSUDUMP) in the job step. The DD 
statement determines the type of dump provided and the system dump options that are used. 
When the dump is taken, the dump options that you requested (specified in the ABEND macro 
instruction or by recovery routines) are added to the installation-selected options. 



Dumping Services 



exit. 



A snap dump obtained through use of the SNAP macro instruction. 



ABEND Dumps 
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Note: The operator can use the CHNGDUMP command either to alter the dump options you 
or the installation specified, or to suppress all ABEND dumps. 

If a dump is requested and the ESTAE/ESTAI routine also requests retry, the control program 
takes the dump before passing control to the retry address. 

The data set containing the dump can reside on any device supported by the basic sequential 
access method (BSAM). The dump is placed in the data set described by the DD statement you 
provide. If you select a printer, the dump is printed immediately. However, if you select a 
direct access or tape device, you must schedule a separate job to obtain a hsting of the dump, 
and to release the space on the device. If the dump data set was described by a SYSMDUMP 
DD statement, you can use the AMDPRDMP service aid to format and print the dump. (Do 
not select a printer for a SYSMDUMP DD statement.) For information about the 
AMDPRDMP service aid see SPL: Service Aids. 

Obtaining a Symptom Dump 

With all ABEND dumps, you will automatically receive a short symptom dump of 
approximately ten lines. This symptom dump provides a summary of error information, which 
will help you to identify dupUcate problems. 

You will receive this dump even without a DD statement unless your installation changes the 
default via the CHNGDUMP operator command or the dump parmUb member for 
SYSUDUMP. 

SNAP Dumps 

A task can request a SNAP dump at any time during its processing by issuing a SNAP macro 
instruction. For a SNAP dump, the DD statement can have any name except SYSABEND, 
SYSMDUMP, and SYSUDUMP. 

Like the ABEND dimip, the data set containing the dump can reside on any device that is 
supported by BSAM. The dump is placed in the data set described by the DD statement you 
provide. If you select a printer, the dimip is printed immediately. However, if you select a 
direct access or tape device, you must schedule a separate job to obtain a Usting of the dump, 
and to release the space on the device. 

To obtain a dump using the SNAP macro instruction, you must provide a data control block 
and issue an OPEN macro instruction for the data set before issuing any SNAP macro 
instructions. If the standard dump format is requested, 120 characters per hne are printed. The 
data control block must contain the following parameters: DSORG = PS, RECFM = VBA, 
MACRF=W, BLKSIZE = 882 or 1632, and LRECL= 125. (The data control block is 
described in Data Management Services Guide and Data Management Macro Instructions. If a 
high-density dump is to be printed on a 3800 Printing Subsystem, 204 characters per line are 
printed. To obtain a high-density dump, code CHARS = DUMP on the DD statement 
describing the dump data set. The BLKSIZE= must be either 1470 or 2724, and the 
LRECL= must be 209. CHARS = DUMP can also be coded on the DD statement describing 
a dump data set that will not be printed immediately. If CHARS = DUMP is specified and the 
output device is not a 3800, print Unes are truncated and print data is lost. If your program is 
to be processed by the loader, you should also issue a CLOSE macro instruction for the SNAP 
data control block. 
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Finding Information in a SNAP Dump 

You will obtain a dump index with each SNAP dump. The index will help you find 
information in the dump more quickly. Included in the information in the dump index is an 
alphabetical Ust of the active load modules in the dump along with the page number in the 
dump where each starts. 

Obtaining a Summary Dump 

You can request a summary dump for an abending task by coding the SUM option of the 
SNAP macro instruction. You can also obtain a sunmiary dimip by coding the DUMPOPT 
option of the ABEND or SETRP macro instruction and specifying a list form of SNAP that 
contains the SUM option. 

If SUM is the only option that you specify, the dump will contain a dump header, control 
blocks, and the other areas listed below. The dump header for all ABEND dumps contains the 
following information: 

• The dump title 

• The ABEND code and program status word (PSW) at the time of the error 

• If the PSW contains the address of an active load module: 

- The name and address from the PSW of the load module in error 

— The offset, into this load module, at which the error occurred 

The control blocks and other areas consist of the following information: 

• The control blocks dumped for the CB option 

• The error control blocks (RTM2WAs and SCBs) 

• The save areas 

• The registers at the time of the error 

• The contents of the load module (if the PSW contains the address of an active load 
module) 

• The module pointed to by the last PRB (if it can be found) 

• IK of storage before and after the addresses pointed to by the PSW and the registers at the 
time of the error 

Note: This storage will only be dumped if the caller is authorized to obtain it. The storage 
is printed by ascending storage addresses, with duplicate addresses removed. 

• The supervisor trace table consisting of all trace entries for the ASID that is being dumped. 

Note: The GTF trace records are not included in the dump. 
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If you specify other options in addition to SUM, the summary dump is dispersed throughout 
the dump. For example, if you specify the options: 

CB , SUM , SPLS , LSQA , ERR , TRT 

The dimip will contain the following information: 

• Dump title (SUM) 

• ABEND code and PSW (SUM) 

• Name and address from the PSW of the module in error (SUM) 

• Offset into the module where the error occurred (SUM) 

• Control blocks (SUM and CB) 

• Error control blocks (ERR) 

• Save areas (SUM) 

• LSQA (LSQA) 

• Registers at the time of the error (SUM) 

• Contents of the active load module (SUM) 

• IK of storage before and after the addresses in the PSW and the registers at the time of the 
error (SUM) 

• Subpool data (SPLS) 

• If system trace is active, the system trace data and if GTF is active, the GTF trace data 
(TRT) 
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Virtual Storage Management 



Use the virtual storage area assigned to your job step through implicit and explicit requests for 
virtual storage. The use of a LINK macro instruction is an example of an implicit request; the 
control program allocates storage before bringing the load module into your job pack area. 
The use of the GETMAIN macro instruction is an expUcit request for a certain number of 
bytes of virtual storage to be allocated to the active task. In addition to your requests for 
virtual storage, requests are made by the control program and data management routines for 
areas to contain some of the control blocks required to manage your tasks. 

Note: If your job step is to be executed as a nonpageable (V = R) task, the REGION 
parameter value specified on the job or execute statement determines the amount of virtual 
(real) storage reserved for the job step. If you run out of storage because of a system failure, 
such as in a GETMAIN request, increase the REGION parameter size. 

The following paragraphs discuss some of the techniques that can be applied for efficient use of 
the virtual storage area reserved for your job step. These techniques apply as well to the data 
management portions of your programs. The specific data management storage allocation 
facilities are discussed in the Data Management Services Guide and Data Management Macro 
Instructions pubhcations; the principles discussed here provide the background you need to use 
these facilities. 



Explicit Requests for Virtual Storage 

Virtual storage can be explicitly requested for the use of the active task by issuing a GETMAIN 
macro instruction. The request is satisfied by allocating a portion of the virtual storage area 
reserved for the job step. The virtual storage area is usually not set to zero when allocated. 
(The storage is zeroed for the initial allocation of a page). 

You release virtual storage by issuing a FREEMAIN macro instruction. This does not release 
the area from control of the job step, but makes the area available to satisfy the requirements 
of additional requests for any task in the job step. The virtual storage assigned to a task is also 
given up to a different task in the same job step when the task terminates, except as indicated 
under "Subpool Handling." Releasing virtual storage for use by other job steps is discussed 
under "Relinquishing Virtual Storage." 

Specifying the Size of the Area 

Virtual storage areas are always allocated to the task in multiples of eight bytes and may begin 
on either a doubleword or page boundary. The request for virtual storage is given in terms of 
bytes; if the number specified is not a multiple of eight, it is rounded to the next higher multiple 
of eight. You can make repeated requests for a small number of bytes as you need the area or 
you can make one large request to completely satisfy the requirements of the task. There are 
two reasons for making one large request: it is the only way you can be sure of getting 
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contiguous storage and avoid fragmenting your address space, and because you only make one 
request, the amount of control program overhead is less. 

Types of Explicit Requests 

There are several methods of explicitly requesting virtual storage using a GETMAIN macro 
instruction. Each of the methods, which are designated by coding an associated character in 
the parameter field of the GETMAIN macro instruction, has certain advantages, depending on 
the requirements of your program. You can specify the actual location (above or below 16 Mb) 
of the virtual area allocated by using the LOG parameter of the GETMAIN macro instruction. 
(LOG is valid only with RU, RC, VRU, and VRG.) If you code LOG = ANY and the subpool 
indicated is supported above 16 Mb, GETMAIN attempts to allocate the virtual storage area 
above 16 Mb. If this is not possible or if the subpool is not supported above 16 Mb, 
GETMAIN allocates the area below 16 Mb. 

The last three methods do not produce reenterable coding unless coded in the list and execute 
forms. (See the topic "Implicit Requests" for additional information.) When you use the last 
three types, you can allocate storage below 16 Mb only. 

The methods and the characters associated with them follow: 

Register Type: There are several kinds of register requests. In each case the address of the 
area is returned in register 1. All of the register requests produce reenterable code because the 
parameters are passed to the control program in registers, not in a parameter Ust. The register 
requests are as follows: 

R specifies a request for a single area of virtual storage of a specified length, located below 16 Mb. 

RU or RC specifies a request for a single area of virtual storage of a specified length, located above or below 16 
Mb according to the LOC parameter. 

VRU or VRC specifies a request for a single area of virtual storage with length between two values that you specify, 
located above or below 16 Mb according to the LOC parameter. GETMAIN attempts to allocate the 
maximum length you specify. If not enough storage is available to allocate the maximum length, 
GETMAIN allocates the largest area with a length between the two values that you specified. 
GETMAIN returns the length in register 0. 

Element Type: EC or EU specifies a request for a single area of virtual storage, below 16 Mb, 
of a specified length. GETMAIN places the address of the allocated area in a fuUword that 
you supply. 

Variable Type: VC or VU specifies a request for a single area of virtual storage below 16 Mb 
with a length between two values you specify. GETMAIN attempts to allocate the maximum 
length you specify; if not enough storage is available to allocate the maximum length, the 
largest area with a length between the two values is allocated. GETMAIN places the address of 
the area and the length allocated in two consecutive fullwords that you supply. 

List Type: LC or LU specifies a request for one or more areas of virtual storage, below 16 
Mb, of specified lengths. 

In addition to the above methods of requesting virtual storage, you can designate the request as 
conditional or unconditional. If the request is unconditional and sufficient virtual storage is not 
available to fill the request, the active task is abnormally terminated. If the request is 
conditional, however, and insufficient virtual storage is available, a return code of 4 is provided 
in register 15; a return code of 0 is provided if the request was satisfied. 
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An example of using the GETMAIN macro instruction is shown in Figure 38, The example 
assumes a program that operates most efficiently with a work area of 16,000 bytes, with a fair 
degree of efficiency with 8,000 bytes or more, inefficiently with less than 8,000 bytes. The 
program uses a reenterable load module having an entry name of REENTMOD, and will use it 
again later in the program; to save time, the load module was brought into the job pack area 
using a LOAD macro instruction so that it will be available when it is required. 



GETMAIN EC, LV= 16000, A=ANSWADD 



PR0CEED2 
PROCEED 1 
MIN 
SIZES 

ANSWADD 



LTR 
BZ 

DELETE 



15,15 
PROCEED 1 
EP=REENTMOD 



GETMAIN VU , LA=S I ZES , A=ANSWADD 



L 

CH 
BNL 



DC 
DC 
DC 
DC 
DC 



4,ANSWADD+4 
4, MIN 
PROCEED 1 



H'8000' 
F'4000' 
F' 16000' 
F'O' 
F'O' 



Conditional request for 16,000 bytes 
in processor storage 
Test return code 

If 16,000 bytes allocated, proceed 
If not, delete module and try to get 
smaller amount of virtual storage 
Load and test allocated length 
If 8,000 or more, use procedure 1 
If less than 8,000 use procedure 2 



Min. size for procedure 1 

Min. size for procedure 2 

Size of area for maximum efficiency 

Address of allocated area 

Size of allocated area 



Figure 38. Using the GETMAIN Macro Instruction 

A conditional request for a single element of storage with a length of 16,000 bytes is requested 
in Figure 38. The return code in register 15 is tested to determine if the storage is available; if 
the return code is 0 (the 16,000 bytes were allocated), control is passed to the processing 
routine. If sufficient storage is not available, an attempt to obtain more virtual storage is made 
by issuing a DELETE macro instruction to free the area occupied by the load module 
REENTMOD. A second GETMAIN macro instruction is issued, this time an unconditional 
request for an area between 4,000 and 16,000 bytes in length. If the minimum size is not 
available, the task is abnormally terminated. If at least 4,000 bytes are available, the task can 
continue. The size of the area actually allocated is determined, and one of the two procedures 
(efficient or inefficient) is given control. 

Cell Pool Services 

The cell pool macro instruction (CPOOL) provides users with another way of obtaining virtual 
storage. This macro instruction provides centralized, high performance cell management 
services. 

Cell pool services obtain a block of virtual storage (called a cell pool) from a specified subpool 
at the user's request. The user can then request smaller blocks of storage (called cells) from this 
cell pool as needed. If the storage for the requested cells exceeds the storage available in the 
cell pool, the user can also request that the cell pool be increased in size (extended) to fill all 
requests. 
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The CPOOL macro instruction provides the user with the following cell pool services: 

• Create a cell pool (BUILD) 

• Obtain a cell from a cell pool if storage is available (GET,COND) 

• Obtain a cell from a cell pool and extend the cell pool if storage is not available 
(GET,UNCOND) 

• Return a cell to the cell pool (FREE) 

• Free all storage for a cell pool (DELETE) 
Subpool Handling 

In an operating system, subpools of virtual storage are provided to assist in virtual storage 
management and for communications between tasks in the same job step. Because the use of 
subpools requires some knowledge of how the control program manages Adrtual storage, a 
discussion of virtual storage control is presented here. 

Virtual Storage Control: When the job step is given a region of virtual storage, all of the 
storage area available for your use within that region is unassigned. Subpools are created only 
when a GETMAIN macro instruction is issued designating a subpool nimiber (other than 0) 
not previously specified. If no subpool number is designated, the virtual storage is allocated 
from subpool 0, which is created for the job step by the control program when the job-step task 
is initiated. 

The PSW key of the requestor is assigned to the subpool and does not change. A task, if it is 
authorized to do so, can change its PSW key. Such a change makes a previously acquired 
subpool unusable because the subpool's key no longer matches the task's key. 

For purposes of control and virtual storage protection, the control program considers all virtual 
storage within the region in terms of 4096-byte blocks. These blocks are assigned to a subpool, 
and space within the blocks is allocated to a task by the control program when requests for 
virtual storage are made. When there is sufBdent unallocated virtual storage within any block 
assigned to the designated subpool to fill a request, the virtual storage is allocated to the active 
task from that block. If there is insufficient unallocated virtual storage within any block 
assigned to the subpool, a new block (or blocks, depending on the size of the request) is 
assigned to the subpool, and the storage is allocated to the active task. The blocks assigned to 
a subpool are not necessarily contiguous unless they are assigned as a result of one request. 
Only blocks within the region reserved for the associated job step can be assigned to a subpool. 

Figure 39 is a simpUfied view of a virtual-storage region containing four 4096-byte blocks of 
storage. All the requests are for virtual storage from subpool 0. The first request from some 
task in the job step is for 1008 bytes; the request is satisfied from the block shown as Block A 
in the figure. The second request, for 4000 bytes, is too large to be satisfied from the unused 
portion of Block A, so the control program assigns the next available block. Block B, to 
subpool 0, and allocates 4000 bytes from Block B to the active task. A third request is then 
received, this time for 2000 bytes. There is enough area in Block A (blocks are checked in the 
order first in, first out), so an additional 2000 bytes are allocated to the task from Block A. All 
blocks are searched for the closest fitting free area which will then be assigned. If the request 
had been for 96 bytes or less, it would have been allocated from Block B. Because all tasks 
may share subpool 0, Request 1 and Request 3 do not have to be made from the same task, 
even though the areas are contiguous and from the same 4096 byte block. Request 4, for 6000 
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bytes, requires that the control program allocate the area from 2 contiguous blocks which were 
previously unassigned, Block D and Block C. These blocks are assigned to subpool 0. 




Figure 39. Virtual Storage Control 

As indicated in the preceding example, it is possible for one 4096-byte block in subpool 0 to 
contain many small areas allocated to many different tasks in the job step, and it is possible 
that numerous blocks could be split up in this manner. Areas acquired by a task other than the 
job-step task are not released automatically on task termination. Even if FREEMAIN macro 
instructions were issued for each of the small areas before a task terminated, the probable result 
would be that many small unused areas would exist within each block while the control 
program would be continually assigning new blocks to satisfy new requests. To avoid this 
situation, you can define subpools for exclusive use by individual tasks. 

Any subpool can be used exclusively by a single task or shared by several tasks. Each time that 
you create a task, you can specify which subpools are to be shared. Unlike other subpools, 
subpool 0 is shared by a task and its subtask, unless you specify otherwise. When subpool 0 is 
not shared, the control program creates a new subpool 0 for use by the subtask. As a result, 
both the task and its subtask can request storage from subpool 0 but both will not receive 
storage from the same 4096-byte block. When the subtask terminates, its virtual storage areas 
in subpool 0 are released; since no other tasks share this subpool, complete 4096-byte blocks are 
made available for reallocation. 

Note: If the storage is shared, it is not released until the owning task terminates. 

When there is a need to share subpool 0, you can define other subpools for exclusive use by 
individual tasks. When you first request storage from a subpool other than subpool 0, the 
control program assigns a new 4096-byte block to that subpool, and allocates storage from that 
block. The task that is then active is assigned ownership of the subpool and, therefore, of the 
block. When additional requests are made by the same task for the same subpool, the requests 
are satisfied by allocating areas from that block and as many additional blocks as are required. 
If another task is active when a request is made with the same subpool number, the control 
program assigns a new block to a new subpool, allocates storage from the new block, and 
assigns ownership of the new subpool to the second task. 
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A task can specify subpools numbered from 0 to 127. FREEMAIN macro instructions can be 
issued to release any complete subpool except subpool 0, thus releasing complete 4096-byte 
blocks. When a task terminates, its unshared subpools are released automatically. 

Owning and Sharing: A subpool is initially owned by the task that was active when the 
subpool was created. The subpool can be shared with other tasks, and ownership of the 
subpool can be assigned to other tasks. Two macro instructions are used in the handUng of 
subpools: the GETMAIN macro instruction and the ATTACH macro instruction. In the 
GETMAIN macro instruction, the SP parameter can be written to request storage from 
subpools 0 to 127; if this parameter is omitted, subpool 0 is assumed. The parameters that deal 
with subpools in the ATTACH macro instruction are: 

• GSPV and GSPL, which give ownership of one or more subpools (other than subpool 0) to 
the task being created. 

• SHSPV and SHSPL, which share ownership of one or more subpools (other than subpool 
0) with the new subtask. 

• SZERO, which determines whether subpool 0 is shared with the subtask. 

All of these parameters are optional. If they are omitted, no subpools are given to the subtask, 
and only subpool 0 is shared. 

Creating a Subpool: If the subpool specified does not exist for the active task, a new subpool is 
created whenever SHSPV or SHSPL is coded on an ATTACH macro instructions or a 
GETMAIN macro instruction is issued. A new subpool zero is created for the subtask if 
SZERO = NO is specified on ATTACH. If one of the ATTACH macro instruction parameters 
that specifies shared ownership of a subpool causes the subpool to be created, the subpool 
number is entered in the list of subpools owned by the task, but no blocks are assigned and no 
storage is actually allocated. If a GETMAIN macro instruction results in the creation of a 
subpool, the subpool number is assigned to one or more 4096-byte blocks, and the requested 
storage is allocated to the active task. In either case, ownership of the subpool belongs to the 
active task; if the subpool is created because of an ATTACH macro instruction, ownership is 
transferred or retained depending on the parameter used. 

Transferring Ownership: An owning task gives ownership of a subpool to a direct subtask by 
using the GSPV or GSPL parameters in the ATTACH macro instruction issued when that 
subtask is created. Ownership of a subpool can be given to any subtask of any task, regardless 
of the control level of the two tasks involved and regardless of how ownership was obtained. A 
subpool cannot be shared with one or more subtasks and then transferred to another subtask, 
however; an attempt to do this results in abnormal termination of the active task. Ownership 
of a subpool can only be transferred if the active task has sole ownership; if the active task is 
sharing a subpool and an attempt is made to transfer it to a subtask, the subtask receives 
shared control and the originating task reUnquishes the subpool. Once ownership is transferred 
to a subtask or rehnquished, any subsequent use of that subpool number by the originating task 
results in the creation of a new subpool. When a task that has ownership of one or more 
subpools terminates, all of the virtual storage areas in those subpools are released. Therefore, 
the task with ownership of a subpool should not terminate until all tasks or subtasks sharing 
the subpool have completed their use of the subpool. 

If GSPV or GSPL specifies a subpool which does not exist for the active task, no action is 
taken. 
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Sharing a Subpool: Shared use of a subpool can be given to a direct subtask of any task with 
ownership or shared control of the subpool. Shared use is given by specifying the SHSPV or 
SHSPL parameters in the ATTACH macro instruction issued when the subtask is created. Any 
task with ownership or shared control of the subpool can add to or reduce the size of the 
subpool through the use of GETMAIN and FREEMAIN macro instructions. When a task 
that has shared control of the subpool terminates, the subpool is not affected. 

Subpook in Task Communication: The advantage of subpools in virtual storage management is 
that, by assigning separate subpools to separate subtasks, the breakdown of virtual storage into 
small fragments is reduced. An additional benefit from the use of subpools can be realized in 
task communication. A subpool can be created for an originating task and all parameters to be 
passed to the subtask placed in the subpool. When the subtask is created, the ownership of the 
subpool can be passed to the subtask. After all parameters have been acquired by the subtask, 
a FREEMAIN macro instruction can be issued, under control of the subtask, to release the 
subpool virtual storage areas. In a similar manner, a second subpool can be created for the 
originating task, to be used as an answer area in the performance of the subtask. When the 
subtask is created, the subpool ownership would be shared with the subtask. Before the subtask 
is terminated, all parameters to be passed to the originating task are placed in the subpool area; 
when the subtask is terminated, the subpool is not released, and the originating task can acquire 
the parameters. After all parameters have been acquired for the originating task, a 
FREEMAIN macro instruction again makes the area available for reuse. 



Implicit Requests for Virtual Storage 

You make an implicit request for virtual storage every time you issue a LINK, LOAD, 
ATTACH, or XCTL macro instruction. In addition, you make an implicit request for virtual 
storage when you issue an OPEN macro instruction for a data set. This section discusses some 
of the techniques you can use to cut down on the amount of real storage required by a job step, 
and the assistance given you by the control program. 

Reenterable Load Modules 

A reenterable load module is designed so that during execution it does not modify itself Only 
one copy of the load module is paged into real storage to satisfy the requirements of any 
number of tasks in a job step. This means that even though there are several tasks in the job 
step and each task concurrently uses the load module, the only real storage needed is an area 
large enough to hold one copy of the load module (plus a few bytes for control blocks). The 
same amount of real storage would be needed if the load module were serially reusable; 
however, the load module could not be used by more than one task at a time. 

Reenterable Macro Instructions 

All of the macro instructions described in this manual can be written in reenterable form. 
These macro instructions are classified as one of two types: macro instructions that pass 
parameters in registers 0 and 1, and macro instructions that pass parameters in a list. The 
macro instructions that pass parameters in registers present no problem in a reenterable 
program; when the macro instruction is coded, the required parameter values should be 
contained in registers. For example, the POST macro instruction requires that the ECB address 
be coded as follows: 

POST ecb address 
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One method of coding this in a reenterable program would be to require this address to refer to 
a portion of storage that has been allocated to the active task through the use of a GETMAIN 
macro instruction. The address would change for each use of the load module. Therefore, you 
would load one of the general registers 2-12 with the address, and designate that register when 
you code the macro instruction. If register 4 contains the ECB address, the POST macro 
instruction is written as follows: 

POST (4) 

The macro instructions that pass parameters in a list require the use of special forms of the 
macro instruction when used in a reenterable program. The macro instructions that pass 
parameters in a list are identified within their descriptions in the macro instruction section of 
this manual. The expansion of the standard form of these macro instructions results in an 
in-line parameter Ust and executable instructions to branch around the Hst, to load the address 
of the list, and to pass control to the required control program routine. The expansions of the 
list and execute forms of the macro instruction simply divide the functions provided in the 
standard form expansion: the list form provides only the parameter Ust, and the execute form 
provides executable instructions to modify the list and pass control. You provide the 
instructions to load the address of the Ust into a register. 

The Ust and execute forms of a macro instruction are used in conjunction to provide the same 
services available from the standard form of the macro instruction. The advantages of using Ust 
and execute forms are as follows: 

• Any parameters that remain constant in every use of the macro instruction can be coded in 
the list form. These parameters can then be omitted in each of the execute forms of the 
macro instruction which use the list. This can save appreciable coding time when you use a 
macro instruction many times. (Any exceptions to this rule are Usted in the description of 
the execute form of the appUcable macro instruction.) 

• The execute form of the macro instruction can modify any of the parameters previously 
designated. (Again, there are exceptions to this rule.) 

• The Ust used by the execute form of the macro instruction can be located in a portion of 
virtual storage assigned to the task through the use of the GETMAIN macro instruction. 
This ensures that the program remains reenterable. 

Figure 40 shows the use of the Ust and execute forms of a DEQ macro instruction in a 
reenterable program. The length of the list constructed by the list form of the macro 
instruction is obtained by subtracting two symboUc addresses; virtual storage is allocated and 
the Ust is moved into the allocated area. The execute form of the DEQ macro instruction does 
not modify any of the parameters in the list form. The list had to be moved to allocated 
storage because the control program can store a return code in the Ust when RET = HAVE is 
coded. Note that the coding in a routine labeled MOVERTN is vaUd for lengths up to 256 
bytes only. Some macro instructions do produce lists greater than 256 bytes when many 
parameters are coded (for example, OPEN and CLOSE with many data control blocks, or ENQ 
and DEQ with many resources), so in actual practice a length check should be made. The 
move long instruction (MVCL) should be considered for moving large data Usts. 
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LA 3,MACNAME Load address of list form 

LA 5,NSIADDR Load address of end of list 

SR 5,3 Length to be moved in register 5 

BAL 14,M0VERTN Go to routine to move list 

DEQ ,MF=(E,(1)) Release allocated resource 



* The MOVERTN allocates storage from subpool 0 and moves up to 256 

* bytes into the allocated area. Register 3 is from address, 

* register 5 is length. Area address returned in register 1. 



MOVERTN 



MOVE INST 



GETMAIN R,LV=(5) 



LR 

BCTR 
EX 
BR 
MVC 



4,1 
5,0 

5, MOVE INST 
14 

0(0, 4), 0(3) 



Address of area in register 4 
Subtract 1 from area length 
Move list to allocated area 
Return 



MACNAME 
NSIADDR 
NAMEl 
NAME2 



DEQ (NAMEl ,NAME2 , 8 , SYSTEM) ,RET=HAVE ,MF=L 

DC CL8' MAJOR' 

DC CL8' MINOR' 



Instruction in a Reenterable Program 

Figure 40. Using the List and the Execute Forms of the DEQ Macro 



Nonreenterable Load Modules 

The use of reenterable load modules does not automatically conserve virtual storage; in many 
applications it will actually prove wasteful. If a load module is not used in many jobs and if it 
is not employed by more than one task in a job step, there is no reason to make the load 
module reenterable. The allocation of virtual storage for the purpose of moving coding from 
the load module to the allocated area is a waste of both time and virtual storage when only one 
task requires the use of the load module. 

You should not make a load module reenterable or serially reusable if reusability is not really 
important to the logic of your program. Of course, if reusability is important, you can issue a 
LOAD macro instruction to load a reusable module, and later issue a DELETE macro 
instruction to release its area. 

Notes: 

1. If your module is reenterable or serially reusable, the load module must be link edited, with 
the desired attribute, into a library. 

2. A module that does not modify itself (a refreshable module) reduces paging activity because it 
does not need to be paged out. 
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Freeing of Virtual Storage 

The control program establishes two responsibility counts for every load module brought into 
virtual storage in response to your requests for that load module. The responsibility counts are 
lowered as follows: 

• If the load module was requested in a LOAD macro instruction, that responsibility count is 
lowered when using a DELETE macro instruction. 

• If the load module was requested in a LINK, ATTACH, or XCTL macro instruction, that 
responsibility count is lowered when using an XCTL macro instruction or by returning 
control to the control program. 

• When a task is terminated, the responsibility counts are lowered by the number of requests 
for the load module made in LINK, LOAD, ATTACH, and XCTL macro instructions 
during the performance of that task, minus the number of deletions indicated above. 

The virtual storage area occupied by a load module is released when the responsibility counts 
reach zero. When you plan your program, you can design the load modules to give you the 
best trade-off between execution time and efficient paging. If you use a load module many 
times in the course of a job step, issue a LOAD macro instruction to bring it into virtual 
storage; do not issue a DELETE macro instruction until the load module is no longer needed. 
Conversely, if a load module is used only once during the job step, or if its uses are widely 
separated, issue a LINK macro instruction to obtain the module and issue an XCTL from the 
module (or return control to the control program) after it has been executed. 

There is a minor problem involved in the deletion of load modules containing data control 
blocks. An OPEN macro instruction must be issued before the data control block is used, and 
a CLOSE macro instruction issued when it is no longer needed. If you do not issue a CLOSE 
macro instruction for the data control block, the control program issues one for you when the 
task is terminated. However, if the load module containing the data control block has been 
removed from virtual storage, the attempt to issue the CLOSE macro instruction causes 
abnormal termination of the task. You must either issue the CLOSE macro instruction yourself 
before deleting the load module, or ensure that the data control block is still in virtual storage 
when the task is terminated (possibly by issuing a GETMAIN and creating the DCB in the area 
that had been allocated by the GETMAIN). 
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Data-in-Virtual 



Data-in-virtual simplifies the writing of applications that use large amounts of data from 
permanent storage. Applications can create, read, and update data without the I/O buffer, 
blocksize, and record considerations that the traditional GET and PUT types of access methods 
require. Moreover, by using the services of data-in-virtual, certain applications that access large 
amounts of data can potentially improve their performance and their use of system resources. 

Such applications have an accessing pattern that is non-sequential and unpredictable. This kind 
of pattern is a function of conditions and values that are revealed only in the course of the 
processing. In these applications, the sequential record subdivisions of conventional access 
methods are meaningless to the central processing algorithm. It is difficult to adapt this class of 
applications to conventional record management programming techniques, which require all 
permanent storage access to be fimdamentally record-oriented. Through the DIV macro, 
data-in-virtual provides these applications a way to manipulate the data without the constraints 
of record-oriented processing. 

An application written for data-in-virtual views its permanent storage data as a seamless body 
of data without internal record boundaries. By using the data-in-virtual MAP service, the 
application can make any portion of the data set appear in virtual storage, in an area that is 
called a virtual storage window. Then, the data in the window can be referenced and updated 
with conventional processor instructions that access memory. When the application decides to 
copy the updates to the data set, it uses the data-in-virtual SAVE service. 

The data-in-virtual services process the application data in 4096-byte units that are on page 
(4096-byte) boundaries. The processing is similar to that of paging data set support, but a 
special type of permanent data set is used to store the application data. This type of data set, 
which is called a linear data set, is supported by Access Method Services and is referred to in 
this book as a data-in-virtual object, a data object, or simply, an object. The data-in-virtual 
object is truly a continuous string of uninterrupted data. 



Data-in- Virtual 83 



Defining a Linear Data Set 

Before you can use the DIV macro to process a linear data set, the data set must exist on 
permanent storage. 

To create the data set, you need to specify the DEFINE CLUSTER function of IDCAMS with 
the LINEAR parameter. When you use DEFINE CLUSTER, it is strongly recommended that 
you specify the SHAREOPTIONS(l,3) parameter with a dataset disposition parameter of ,SHR 
in the JCL. This permits multiple readers or a single updater to access the linear data set. The 
system does not provide suitable data set integrity if any other values are specified for 
SHAREOPTIONS. 

The following JCL invokes Access Method Services (IDCAMS) to create the linear data set 
named DIV.SAMPLE on the volume called DIVPAK. When IDCAMS creates the data set, it 
creates it as an empty data set. Note that no RECORDS parameter is used because linear data 
sets do not have records. 



//JNAME 


JOB • ALLOCATE LINEAR ' , MSGLEVEL= (1,1), 


// 


CLASS=R ,MSGCLASS=D , USER= JOHNDOE 


//* 




//* 




//* 


ALLOCATE A VSAM LINEAR DATASET 


//* 




//CLUSTPG 


EXEC PGM=IDCAMS,REGION=4096K 


//SYSPRINT 


DD SYSOUT=* 


//DIVPAK 


DD UNIT=3 380 , VOL=SER=DIVPAK , DISP=OLD 


//SYSIN 


DD * 




DEFINE CLUSTER (NAME ( DIV. SAMPLE ) - 




VOLUMES (DIVPAK) - 




TRACKS (1,1) - 




SHAREOPTIONS ( 1 , 3 ) - 




LINEAR) 


/* 





For further information on the creation of linear VSAM data sets and the alteration of 
entry-sequenced VSAM data sets, see MVS/Extended Architecture Integrated Catalog 
Administration: Access Method Services Reference . 
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Using the Services Of Data-in- Virtual 



Each invocation of the DIV macro requests any one of eigHt distinct services provided by 
data-in-virtual: 

• IDENTIFY 

• ACCESS 

• MAP 

• SAVE 

• RESET 

• UNMAP 

• UNACCESS 

• UNIDENTIFY 

Identify 

To request processing of a data-in-virtual object, an application must invoke the IDENTIFY 
service. The application uses IDENTIFY to tell the system which data-in-virtual object it wants 
to process, via the DDNAME parameter. IDENTIFY generates a unique id, or token, that 
uniquely represents the appUcation's individual request to use the given data set. It returns this 
id to the application. When the application requests other kinds of services with the DIV 
macro, it supplies this id as an input parameter. 

Access 

To access the object, an application must use the ACCESS service. ACCESS is similar to the 
OPEN macro of VSAM. It has a mode parameter of READ or UPDATE, and it gives your 
application the right to read or update the object. ACCESS excludes other appUcations from 
reading and updating the object, as determined by the current SHAREOPTIONS definition for 
the object. You normally invoke ACCESS after you invoke IDENTIFY and before you invoke 
MAP. 



The data object is stored in units of 4096-byte blocks. An application uses the MAP service to 
specify the part of the object that is to be processed in virtual storage. It can specify the entire 
object (all of the blocks), or a part of the object (any continuous range of blocks). 

After ACCESS, the application issues a GETMAIN macro to obtain a virtual storage area 
large enough to contain the string of blocks that is to be processed. The size of the object, 
which is returned (optionally) by ACCESS, can determine how much virtual storage needs to be 
requested when the application issues GETMAIN. After GETMAIN, the application invokes 
MAP. MAP establishes a direct correspondence between blocks on the object and pages in 
virtual storage. A continuous range of pages corresponds to a continuous range of blocks. This 
correspondence is called a virtual storage window, or a window. 

After MAP, the application can look into the virtual storage area that is framed by the window. 
When it looks into this virtual storage area, it sees the same data that is on the object. When 
the application references this virtual storage area, it is referencing the data from the object, 
which is available in the window whenever a reference is made inside the window. To reference 
the area in the window, the application simply uses any conventional processor instructions that 
access memory. 
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Although the object data becomes available in the window when MAP is used, no actual 
movement of data from the object into the window occurs at that time. Actual movement of 
data from the object to the window can only occur when the application refers to data in the 
window. When a page in the window is referenced for the first time, a page fault occurs. When 
the page fault occurs, the system reads the permanent storage block into real storage. 

When data is read into real storage, the data movement involves only the precise block that is 
referenced, which replaces the corresponding page in the window. Thus, only the blocks that are 
referenced by an application are ever read into real storage. 

Notes: 

1. If the application would rather keep in the window the data that existed before the window 
was established (instead of having the object data appear in the window), it can specify this by 
using the RETAIN parameter. This would be useful when creating an object or overlaying the 
contents of an object. 

2. An important concept for data-in-virtual is the concept of freshly obtained storage. When 
virtual storage has been obtained by a GETMAIN macro and not subsequently modified, the 
storage is considered to be in the freshly obtained state. When referring to this storage or any 
of its included pages, this book uses the terms, "freshly obtained storage" and "freshly 
obtained pages." If a program stores into a freshly obtained page, only that page loses its 
freshly obtained status, while other pages still retain it. 

Save and Reset 

After the MAP service, the appUcation can access the data inside the window directly through 
normal programming techniques. When the application changes some data in the window, 
however, the data on the object does not consequently change. If the application wants the data 
changes in the window to appear in the object, it must use the SAVE service. SAVE causes all 
changed blocks inside the window to be written out to the object. Unchanged blocks are not 
written. When SAVE completes, the object contains any changes that the application made 
inside the virtual storage window. If a SAVE is preceded by another SAVE, the second SAVE 
will only pick up the changes that occurred since the previous SAVE. 

If the appUcation changes some data in a virtual storage window but then decides not to keep 
those changes, it can use the RESET service to remove the changes from the window, 

Unmap 

When the application is finished processing the part of the object that is in the window, it 
eliminates the window by using UNMAP. To process a different part of the object, one not 
already mapped, the application can use the MAP service again. Because parts of the same 
object can be viewed simultaneously through several different windows, the application can set 
up separate windows on the same object. However, a specific page of virtual storage cannot be 
in more than one window at a time. The SAVE, RESET, MAP, and UNMAP services can be 
invoked repeatedly as required by the processing requirements of the appUcation. 
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I Unaccess 



I If the application has temporarily finished processing the object but still has other processing to 

I perform, it uses UNACCESS to relinquish access to the object. Then, other programs can 

I access the object. If the application needs to access the same object again, it can regain access 

I to the object by using the ACCESS service again without having to use the IDENTIFY service 

I again. 

I Unidentify 

I The application uses UNIDENTIFY to revoke its previous request, which was made by 

I IDENTIFY, to process a data-in-virtual object. 



> 
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The roENTIFY Service 



Your program uses IDENTIFY to select the data-in-virtual object that you want to process. 
IDENTIFY has three parameters: ID, DDNAME and TYPE. 

Parameters of IDENTIFY - DDNAME: When you specify the IDENTIFY service, you specify 
a DDNAME parameter that identifies your data-in-virtual object. IDENTIFY causes the 
system to create a unique eight-byte id that it returns to you, stored in the address that you 
specify with the ID parameter. Your program supplies this id as a token input parameter on 
subsequent invocations of other data-in-virtual services. 

Simultaneous requests for different processing activities against the same data-in-virtual object 
can originate from different tasks or from different routines within the same task. Each task or 
routine requesting processing activity against the data set must invoke the identify service. To 
correlate the various DIV macro invocations and processing activities, the eight-byte ids 
generated by IDENTIFY are sufficiently unique to reflect the individuahty of the IDENTIFY 
request, yet they all reflect the same data-in-virtual object. 

Parameters of IDENTIFY - TYPE: The TYPE parameter indicates the storage format of the 
data set name. You must specify TYPE = DA to indicate that the data set name is found in a 
data definition statement. 



The ACCESS Service 

Your program uses the ACCESS service to request permission to read or update the object. 
ACCESS uses three parameters: ID, MODE, and SIZE. 

Parameters of ACCESS - ID: When you issue a DIV macro that requests the ACCESS service, 
you must also specify, on the ID parameter, the identifier that the IDENTIFY service returned. 
The ID parameter tells the system what object you want access to. When you request 
permission to access the object under a specified ID, the system checks the following conditions 
before it grants the access: 

• The ID specified with your ACCESS request has already been estabhshed by a previous 
invocation of IDENTIFY. 

• You have not already accessed the object under the same unique eight-byte ID. Before 
you can reaccess an already-accessed object under the same ID, you must first invoke 
UNACCESS for that ID. 

• If your installation uses RACE, you must have the proper RACE authorization to access 
the object. 

• If you are requesting read access, the object must not be empty. You use the MODE 
parameter to request read or update access. 
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Parameters of ACCESS - MODE: Multiple users (using different IDs) can request access to 
the same object. If you expect multiple users, VSAM serializes their access if you specify 
SHAREOPTIONS(l,3) in the DEFINE CLUSTER access method service request when you 
create the data set. If you specify other than SHAREOPTIONS(l,3), VSAM does not perform 
serialization that is suitable for data-in-virtual usage, and the responsibility for data set 
serialization rests with you. 

When your JCL specifies SHAREOPTIONS(l,3) and a disposition of SHR, the MODE 
parameter determines how your program accesses the object. You can specify a mode parameter 
of READ or UPDATE. READ lets your program share read access to the object with any 
other programs that have requested read access under separate IDs. READ does not let you 
invoke SAVE, which changes the object. However, it does not prevent you from making 
changes in the window. 

UPDATE lets you invoke SAVE to change the data in the object, and it prevents other 
programs from accessing the object. When you request UPDATE, no one else can use the data 
set in either read or update mode. Conversely, when another program is accessing the object in 
update mode, it is impossible for you to read the object or update it. 

Parameters of ACCESS - SIZE: SIZE specifies the address of a four-byte field. When control 

is returned to your program after the ACCESS service executes, the four-byte field contains the 
current size of the object. The size is the number of blocks that must be mapped to ensure that 
the entire object is mapped. If SIZE is omitted or if SIZE = * is specified, the size is not 
returned. 



The MAP Service 

The MAP service is used to make an association between part or all of a data object, the 
portion being specified by the OFFSET and SPAN parameters, and your program's virtual 
storage. This association, which is called a virtual storage window, takes the form of a 
one-to-one correspondence between specified blocks on the object and specified pages in the 
virtual storage. After the MAP is complete, your program can then proceed with the processing 
of the data in the window. The RETAIN parameter specifies whether data that is currently in 
the window is to be retained or to be replaced by the data from the associated object. 

Note: Virtual storage pages that are page-fixed cannot be mapped into a virtual storage 
window. Once the window exists, you can page-fix data inside the window so long as it is not 
fixed when you issue SAVE or UNMAP. 

The DrV macro has five parameters which are used when invoking MAP: ID, OFFSET, 
SPAN, AREA, and RETAIN. 

Parameters of MAP - ID: The ID parameter specifies the storage location containing the 
unique eight-byte value that was returned by IDENTIFY. The map service uses this value to 
determine which object is being mapped under which request. 

If you specify the same ID on multiple invocations of the MAP service, you can create 
simultaneous windows corresponding to different parts of the object. However, an object block 
that is mapped into one window cannot be mapped into any other window created under the 
same ID. If you use different IDs, however, an object block can be included simultaneously in 
several windows. 
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Parameters of MAP - OFFSET and SPAN: The OFFSET and SPAN parameters indicate a 
range of blocks on the object. Blocks in this range appear in the window. OFFSET indicates 
the first object block in the range, while SPAN indicates how many contiguous blocks make up 
the range. An offset of zero indicates the beginning of the object. For example, an offset of zero 
and a span of ten causes the block at the beginning of the object to appear in the window, 
together with the next nine object blocks. The window would then be ten pages long. 

Specifying OFFSET = * or omitting OFFSET causes a default OFFSET of zero to be used. 
Specifying SPAN = 0, SPAN = * or omitting SPAN results in a default SPAN of the number of 
blocks needed to MAP the entire object, starting from the block indicated by OFFSET. 
Specifying both OFFSET = * and SPAN = * or omitting both causes the entire object to appear 
in the window. 

The OFFSET and SPAN parameters may be used to specify a range spanning any portion of 
the object, the entire object, or extending beyond the object. Specifying a range beyond the 
object enables a program to add data to the object, causing the object to grow. If data in a 
mapped range beyond the object is saved (using the SAVE service), the size of the object is 
updated to reflect the new size. 

To use the OFFSET parameter, specify the storage location containing the block offset of the 
first block to be mapped. The offset of the first block in the data object is zero. To use the 
SPAN parameter, specify the storage location containing the number of blocks in the mapped 
range. 

Parameters of MAP - AREA: When you sp)ecify MAP, you must also specify an AREA 
parameter. AREA indicates the beginning of a virtual storage space large enough to contain 
the entire window. Before invoking MAP, you must ensure that this virtual storage space is 
owned by your task. This can be ensured by specifying a storage area that is obtained by the 
GETMAIN macro. The storage must belong to a single, pageable private area subpool. It must 
begin on a 4096-byte boundary (that is, a page boundary) and have a length that is a multiple 
of 4096 bytes. 

Note that any virtual storage space assigned to one window cannot be simultaneously assigned 
to another window. If your MAP request specifies, via the AREA parameter, a virtual storage 
location that is part of another window, the request is rejected. 

A virtual storage area that is mapped into a window cannot be freed as long as the map exists. 
Attempts to do this will result in the virtual space being made unusable and an ABEND of the 
program. Subsequent attempts to reference the mapped virtual space will also result in an 
ABEND. 

Parameters of MAP - RETAIN: The RETAIN parameter determines what data is to be viewed 
in the window. It can be either the contents of the virtual storage area (that corresponds to the 
window) the way it was before you invoked MAP, or it can be the contents of the object. 

If you specify RETAIN = NO, or do not specify the RETAIN parameter at all (which defaults 
to RETAIN = NO), then the contents of the object replaces the contents of the virtual storage 
whenever a page in the window is referenced. Virtual storage that corresponds to a range 
beyond the end of the object appears as binary zeros when referenced. RETAIN = NO can be 
used when you want to view data already on the object, possibly with the intent of changing 
some data and saving it back to the object. 

If you specify RETAIN = YES, then the window retains the contents of virtual storage. The 
data in the window are not replaced by data from the object as a result of the MAP operation. 
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If you issue a subsequent SAVE, the data on the object is REPLACED by the data in the 
window. If the window extends beyond the object and your program has not referenced the 
pages in the extending part of the window, then the extending pages are not saved. However, if 
the extending pages have been referenced, then they are saved on the object, causing the object 
to be extended so it can hold the additional data. 

RETAIN = YES can also be used to reduce the size of (truncate) the object. If the part you 
want to truncate is mapped with RET AIN = YES and the window consists of freshly obtained 
storage, then at SAVE time, the data object size is reduced. 

If you want to have zeroes written at the end of the object, then the corresponding virtual 
storage must be explicitly set to zero prior to the SAVE. 



The SAVE Service 

The SAVE service causes data to be written from virtual storage onto the data-in-virtual object. 
When you invoke SAVE, you specify a single and continuous range of blocks on the 
data-in-virtual object. Any virtual storage windows inside this range are eUgible to participate 
in the SAVE. 

For a SAVE request to be vaUd, the object must currently be accessed with 
MODE = UPDATE, under the same ID as the one specified on this SAVE request. Because an 
object can be mapped beyond its current end, the object might be extended when the SAVE is 
done if there are changed pages beyond the current end at the time of the ACCESS. On the 
other hand, the SAVE truncates the object if freshly obtained pages are mapped in a range that 
extends to or beyond the end of the object. In either case, the new object size is returned to 
your program if you specify the SIZE parameter. 

Pages within the range cannot be page fixed when the SAVE is issued. Mapped pages in the 
range that are freshly obtained are written as binary zeroes if they occur before a changed page. 
The DIV macro has four parameters which are used when invoking SAVE: ID, OFFSET, 
SPAN and SIZE. 

Notes: 

1. If data to be saved has not changed since the last SAVE, no I/O will be performed. The 
performance advantages of using data-in-virtual are primarily because of the automatic 
elimination of unnecessary read and write I/O operations. 

2. The range specified with SA VE refers to the blocks of the object, which relate to pages inside 
a window. 

3. The range specified with SAVE can extend beyond the end of the object. 

4. Pages of the object not mapped to any window are not saved. 

5. Pages in a window that lie outside the specified range are not saved. 

Parameters of SA VE - ID: The ID parameter tells the SAVE service which data object is being 
written to under which request. Use ID to specify the storage location containing the unique 
eight-byte name that was returned by IDENTIFY. The object must have been previously 
accessed with MODE = UPDATE under the same ID as the one specified for SAVE. 
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Parameters of SA VE - OFFSET and SPAN: The OFFSET and SPAN parameters are used to 
select a continuous range of object blocks, within which the SAVE service can operate. 
OFFSET indicates the first block and SPAN indicates the number of blocks in the range. As in 
the MAP service, the offset and span parameters refer to object blocks; they do not refer to 
pages in the window. 

Specifying OFFSET = * or omitting OFFSET causes the default offset (zero) to be used. The 
zero offset does not omit or skip over any of the object blocks, and it causes the range to start 
right at the beginning of the object. Specifying SPAN=0, SPAN = *, or omitting SPAN gives 
you the default span. The default span includes the first object block after the part skipped by 
the offset, and it includes the entire succession of object blocks up to and including the object 
block that corresponds to the last page of the last window. 

When SAVE executes, it examines each virtual storage window established for the object. In 
each window, it detects every page that corresponds to an object block in the selected range. 
Then, if the page has changed since the last SAVE, the page is written on the object. (If the 
page has not changed since the last SAVE, it is already identical to the corresponding object 
block and there is no need for it to be saved.) Although SAVE discriminates between blocks on 
the basis of whether they have changed, it has the effect of saving all window pages that lie in 
the selected range. Specifying both OFFSET = * and SPAN = * or omitting both causes the 
system to save all changed pages in the window without exceptions. 

To use the OFFSET parameter, specify the storage location containing the block offset of the 
first block to be saved. The Offset of the first block in the object is zero. To use the SPAN 
parameter, specify the storage location containing the number of blocks in the range to be 
saved. 

Parameters of SA VE - SIZE: Invoking SAVE can change the size of the object. When you 
specify SIZE, the size of the object after SAVE completes is returned in the virtual storage 
location specified by the SIZE parameter. If you omit SIZE or specify SIZE = *, the size value 
is not returned. 

Effect of RETAIN Mode on SAVE 

While RETAIN cannot be specified on SAVE, the RETAIN mode of each included window 
affects how the window is saved. 

When RETAIN = NO was specified for a previously mapped window, all pages in the virtual 
storage window appear to contain the contents of the object and are considered unchanged with 
respect to the object. When SAVE is issued, only pages in mapped windows that are changed 
and correspond to blocks within the range being saved are written to the object. Pages that 
might have been freshly obtained before the MAP, but have not been referenced since the 
MAP, still are not saved because they appear to contain the data that is on the corresponding 
blocks of the object. As with RETAIN = YES, the size of the object can still increase if the 
saved range extends beyond the current end of the object and it contains mapped windows with 
changed pages. 

When RETAIN = YES was specified for a mapped virtual storage window, all pages in the 
window that are not freshly obtained are considered changed. SAVE writes all these pages, 
which are considered changed, onto the object. If both the range to be saved and the previously 
mapped virtual storage window ranges extend beyond the current end of the object, 
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then the object is extended to hold the additional data. In addition, freshly obtained pages in 
the window will be written to the object as zeroes if: 

• The freshly obtained pages correspond to blocks on the object within the current object 
size. 

• The freshly obtained page currently being saved is followed, in the current window or in 
another window, by one or more changed pages. 

On the other hand, freshly obtained pages in the window will cause the object to shrink in 
size (i.e. to be truncated) if: 

• The freshly obtained page or pages are at the end of the window; that is, there are no 
changed pages beyond the last unchanged page. 

• No other mapped windows beyond the current window contain changed pages. 

• At least one of the freshly obtained pages in the window corresponds to the last block on 
the object; that is, the end of the object is mapped to a freshly obtained page. In this 
situation, the last block of the window must be equal to or greater than the last block of 
the object. 

If all of the listed conditions for truncation are true, then the object is truncated to the last 
block that still contains data, either because (1) it corresponded to the last changed page in a 
mapped window or because (2) there was no mapped window page corresponding to that block. 
In the second case, the block is not affected by the SAVE; it contains the data that existed 
before the SAVE. 



The RESET Service 

At times during program processing, your program might have made changes to pages in the 
virtual storage window, and might no longer want to keep those changes. RESET, which is the 
opposite of SAVE, causes data from the object to appear in the virtual storage window. As 
with SAVE and MAP, the range to be reset refers to the object rather than the virtual storage. 
RESET only resets windows that are within the specified range, and it resets all the windows in 
the range. 

Effect of RETAIN mode on RESET 

Although the RETAIN parameter cannot be specified when you invoke RESET against a 
virtual storage window, the system remembers how RETAIN was specified on the MAP 
operation that created the window. Therefore, when you invoke RESET, the system resets the 
window one way for RETAIN = NO and another way for RETAIN = YES: 

• If the window was created with RETAIN = NO, then after the RESET the data in the 
window is the same as the object data, as of the last SAVE. This applies to all the pages in 
the window. 

• If the window was created with RETAIN = YES, then after the RESET the pages in the 
window acquire a freshly obtained status unless you have been doing SAVE operations on 
this window. Individual object blocks changed by those SAVE operations re-appear after 
the RESET in their corresponding window pages, together with the other pages. However, 
the other pages appear freshly obtained. 
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Note: Regardless of the RETAIN mode of the window, any window page that corresponds to 
a block beyond the end of the object will appear as a freshly obtained page. 

Parameters of RESET - ID: The ID parameter tells the RESET service what data object is 
being written to. Use ID to specify the storage location containing the unique eight-bj^e name 
that was returned by IDENTIFY and used with previous MAP requests. The object must be 
previously accessed (with either MODE = READ or MODE = UPDATE) under the same ID as 
the one being specified for RESET. 

Parameters of RESET - OFFSET and SPAN: The OFFSET and SPAN keywords are used to 
indicate the RESET range, the part of the object that is to supply the data for the RESET. As 
with MAP and SAVE, OFFSET indicates the first object block in the range, while SPAN 
indicates how many contiguous blocks make up the range, starting from the block indicated by 
OFFSET. The first block of the object has an offset of zero. 

To use OFFSET, specify the storage location containing the block offset of the first block to be 
reset. To use SPAN, specify the storage location containing the number of blocks in the range 
to be RESET. Specifying OFFSET = * or omitting OFFSET causes a default OFFSET of zero 
to be used. Specifying SPAN = * or omitting SPAN sets the default to the number of blocks 
needed to reset all the virtual storage windows that are mapped under the specified ID, 
however, starting only with the block number indicated by OFFSET. Specifying both 
OFFSET = * and SPAN = * or omitting both resets all windows that are currently mapped 
under the specified ID. 



The UNMAP Service 

Your program uses the UNMAP service to remove the association between a window in virtual 
storage and the object. Each UNMAP request must correspond to a previous MAP request. 
Note that, because UNMAP has no effect on the object, changes made in virtual storage but 
not yet saved are not saved on the object when UNMAP is issued. UNMAP has three 
parameters: ID, AREA, and RETAIN. 

Parameters of UNMAP - ID: The ID parameter that you specify is the address of an 
eight-byte field in storage. That field contains the identifier associated with the object. The 
identifier is the same value that the IDENTIFY service returned, which is also the same value 
you specified when you issued the corresponding MAP request. 

Parameters of UNMAP - AREA: The AREA parameter specifies the address of a four-byte 
field in storage that contains a pointer to the start of the virtual storage to be unmapped. 
This address must point to the beginning of a window. It is the same address that you 
provided when you issued the corresponding MAP request. 

Parameters of UNMAP - RETAIN: RETAIN specifies the state that virtual storage is to be 
left in after it is unmapped; that is, after the correspondence between virtual storage and the 
object is removed. 

Provided that you specify RETAIN = NO for the MAP service, specifying RETAIN = YES on 
the corresponding UNMAP transfers the value of the object into the window. In this case, 
RETAIN = YES with UNMAP specifies that the virtual storage area corresponding to the 
unmapped window is to contain the same data as the object. After UNMAP, your program 
can still reference and change the data in this virtual storage but can no longer save it on the 
object unless the virtual area is mapped again. 
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specifying RETAIN = NO with UNMAP indicates that the data in the unmapped window is to 
be freshly obtained. 

Notes: 

1. If RETAIN = YES is specified on MAP, RETAIN = YES on the corresponding UNMAP does 
not transfer the object value into the window. In this case. UNMAP leaves the window 
contents unchanged. 

2. If UNMAP is issued with RETAIN = NO, and there are unsaved changes in the virtual storage 
window area, those changes are lost. 

3. If unmap is issued with RETAIN = YES, and there are unsaved changes in thge window, they 
remain in the virtual storage. 

4. The RETAIN parameter of MAP and UNMAP can be used to move data on the object 
without having to physically move it in virtual storage. For example, if you map block 2 to an 
area of virtual storage specifying RETAIN = NO, then block 2 of the object appears in the 
virtual storage window. If you then issue UNMAP with RETAIN^ YES, block 2 is retained 
in virtual storage, even though the correspondence with the object has been removed. 

Then, by mapping the virtual area to block 7 and specifying RETAIN= YES, you set up a 
correspondence between the same virtual area and block 7, with the original data from block 2 
retained in the window. Finally, by issuing SAVE, you save the window (containing the block 
2 data) on block 7 of the object. For more information on RETAIN, see the MAP and SAVE 
services. Note that the second map need not be for the same data object. 

5. Unmapping with RETAIN- YES has certain performance implications. It causes 
unreferenced pages, and maybe some unchanged ones, to be read from the object. 



The UNACCESS and UNIDENTIFY Services 

You use UNACCESS to tenninate your access to the object for the specified ID. UNACCESS 
automatically includes an implied UNMAP. If you issue an UNACCESS with outstanding 
virtual storage windows, any windows that exist for the specified ID are unmapped with 
RETAIN = NO. The ID parameter is the sole parameter of the UNACCESS service, and it 
designates the same ID that you specified in the corresponding ACCESS. As in the other 
services, use ID to specify the storage location containing the unique eight-byte name that was 
returned by IDENTIFY. 

You use UNIDENTIFY to notify the system that your use of an object under the specified ID 
has ended. If the object is still accessed as an object under this ID, UNIDENTIFY 
automatically includes an implied UNACCESS. The UNACCESS, in turn, issues any necessary 
UNMAPs, using RETAIN = NO. The ID parameter is the only parameter for UNIDENTIFY, 
and it must designate the same ID as the one specified in the corresponding ACCESS. As in the 
other services, use ID to specify the storage location containing the unique eight-byte name that 
was returned by IDENTIFY. 
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Conditions for Invocation of Data-in-Virtual 

The services of data-in-virtual execute synchronously, i.e. control is not returned from the DIV 
macro until the service is completed. Thus, before you can successfully invoke a service, the 
previous service must be complete. However, multiple services can be executing concurrently for 
different IDs. To invoke the DIV macro, you can be in the supervisor state, or you can be in 
the problem program state with a user key. You must supply a standard 72 byte save area. To 
issue the DIV macro, you must be: 

1. enabled for I/O and external interrupts. 

2. executing in 31 bit addressing mode. 

3. executing in an environment that allows the use of SVCs. This means that you must be: 

• in task (TCB) mode. 

• not holding any locks. 

• in non-cross memory mode. 

Sharing Services within a Task 

The services of data-in-virtual are task-oriented. When a user issues IDENTIFY, an association 
is established between the ID assigned and the user's task. The type of association differs, 
however, depending on whether the task is authorized or not. The authorized task runs in 
supervisor state, has a system key (0-7), or has APF authorization. The non-authorized task 
runs in problem program state, with a user key, and with no APF authorization. 

• For the non-authorized user, the use of data-in-virtual services for a specific ID is strictly 
local to its immediate task. That is, all services for a particular ID must be requested by the 
same task that requested IDENTIFY, and obtained the ID. 

• For the authorized user, one task can issue IDENTIFY while authorized subtasks of that 
task, using the ID returned by IDENTIFY, can request all the other services, except 
ACCESS. 

However, any task, authorized or not, may reference or change the data in a mapped virtual 
storage window, even if the window was mapped by another task, and even if the object was 
identified and accessed by another task. As long as the task can address the window, it is 
allowed to reference or change the included data. 

Because data-in-virtual services affect virtual storage, the storage protect key of any task that 
requests a service (under a given ID) must be the same as the storage protect key of the task 
that issued the IDENTIFY (that obtained the ID). This is not required if the task has storage 
protect key zero. 

Miscellaneous Restrictions 

• When you attach a new task, you cannot pass ownership of a mapped virtual storage 
window to the new task. That is, the ATTACH keywords GSPV and GSPL cannot be used 
to pass the mapped virtual storage. Ownership of subpool zero cannot be passed using 
GSPV and GSPL keywords. 
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• Data-in-virtual services cannot be invoked in cross memory mode. There are no 

restrictions, however, against referencing and updating a mapped virtual storage window in 
cross memory mode. 



Return Codes, Reason Codes and Abend Codes. 



If control is returned to the user after the DIV macro executes, a return code is supplied in the 
low order (rightmost) byte of general register 15. Successful completion is indicated by a zero 
return code and unsuccessful completion is indicated by a non-zero return code. When control 
is returned after an unsuccessful completion, a reason code is supplied in the two low order 
bytes of general register zero. 



If control is not returned, an abend code and a reason code are supplied, 
values of the reason, return and abend codes are: 

Explanation 



Successful completion. 

Unknown service was requested. 

Unknown parameter list format. 

Input parameter list cannot be addressed. 

Storage specified in the parameter list cannot be 

addressed. 

The parameter list contains a reserved field that 

does not contain binary zeroes. 

The caller is not running in task mode. 

The caller is in cross memory mode. 

An invalid TYPE is specified. 

The supplied ID is not a valid ID or is an ID that 

cannot be used by the caller. 

There is another service currently executing with 

the specified ID. 

The object is already accessed with the specified ID. 

The caller does not have proper RACF 

authorization to the requested object 

The requested window exceeds the maximum 

allowable size for the object. 

The object is not currenUy accessed for the specified 

ID. 

The specified range overlaps a range that is already 

mapped for the specified ID. 

The specified range overlaps another mapped range. 

Undetermined user error. 

The virtual storage specified does not begin on a 

4K bovmdary. 

The virtual storage specified is not in a pageable 
private area subpool. 

The virtual range specified cannot be used to map 
an object. 

The virtual range specified contains at least one 
page that was not obtained by a GETMAIN 
macro, and RETAIN = NO was not specified. 
The virtual range specified contains at least one 
fixed page. 

An I/O error has occurred. 

Caller does not have UPDATE access to the object. 

A page to be saved or reset was in the page fixed 

state. 

The specified range does not encompass any 
mapped area of the object. 
The virtual storage area specified to be unmapped 
is not currently mapped. 

The object cannot be accessed at the current time. 
The accessed object is not at the correct Control 
Interval size. 

The length of the ddname exceeds the maximum 
size allowed. 

The caller's storage protect key is not the same as 
when IDENTIFY was invoked. 



The hexadecimal 



Reason 
code 


Return 
code 


Abend 
code 


none 
0001 

0003 
0004 


on 

none 
none 
none 
none 


none 
08B 

UoXj 

08B 
08B 


0005 


none 


08B 


0006 
0007 
0008 


none 
none 
none 
none 


08B 
08B 
08B 

UOJ3 




Uo 


none 


uuuu 
OOOC 


none 
none 


08B 


nnnr> 


none 


l/OX> 


UUvJD 


none 


UOD 


OOOF 


none 


08B 


0010 
0011 
0012 


none 
none 
none 


08B 
08B 
08B 


0013 


none 


08B 


0014 


none 


08B 


0015 


none 


08B 


0016 


none 


08B 


0017 
0018 
0019 


OC 

none 

none 


none 

08B 

08B 


OOIA 


04 


none 


OOIB 


none 


08B 


OOlC 
OOID 


08 

none 


none 
08B 


OOIE 


none 


OSB 


OOIF 


none 


08B 
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Reason Return Abend 



code 


code 


code 


0020 


none 


08B 


0021 


OC 


none 


0022 


none 


08B 


0023 


none 


08B 


0024 


none 


08B 


0025 


none 


08B 


0026 


none 


08B 


0027 


none 


08B 


0028 


none 


08B 


0801 


08 


none 


0802 


08 


none 


0803 


OC 


none 


0804 


OC 


none 


0805 


none 


08B 


0806 


OC 


none 


0807 


04 


none 


0808 


08 


none 



Explanation 



An ACCESS was attempted by a task that does not 
own the specified ID. 

Portions of the object could not be retained in 

virtual storage as requested. 

The specified storage to be mapped is not owned by 

the task chain that did the IDENTIFY. 

Part or all of the specified storage to be mapped is 

not in the user's key. 

The caller holds the local lock. 

The caller is executing in an environment that 

precludes the use of SVCs. 

The caller is not executing in 31 bit addressing 

mode. 

The specified offset and span describe a range that 
goes beyond the maximum supported object size. 
The caller has attempted to access an empty object 
for reading. 

System error - Insufficient storage available to build 
the necessary data-in-virtual control block 
structure. 

System error - I/O driver failure. 

System error - A necessary page table could not be 

read into real storage. 

System error - Catalog update failed. 

Unexpected system error 

System error - I/O error. 

Media damage may be present in allocated DASD 
space. The damage is beyond the currently saved 
portion of the object. The SAVE completed 
successfully. 

System error - I/O from a previous request has not 
completed. 
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I DIY Macro Programming Examples 



I The following programming examples illustrate how to code and execute a program that 

I processes a data-in-virtual object. 

I Executing an Application 

I The following JCL job causes the execution of an application program called SAMPLE. The 

1 function of SAMPLE is to perform some kind of application-oriented processing on the 

I data-in- virtual object, DIV. SAMPLE, that was allocated in the previous example. 

I When SAMPLE executes, it issues a DIV macro specifying to the IDENTIFY service the name 

I of the data-in-virtual object that it will process. To identify the data set, SAMPLE specifies the 

I ddname, DYNAMIC, on the DDNAME parameter of the DIV macro. 



The system then connects the actual data set name, DIV. SAMPLE, with the program that 
will process it. The Unk between the application program and the data set is the name, 
DYNAMIC, which appears in both the application and the JCL. 



//* 
//* 






//* 


EXECUTE A DATA- IN- VIRTUAL APPLICATION 


//* 




//SAMPLE 


EXEC PGM=SAMPLE 


//STEPLIB 


DD DSN=DIV22.LOAD. JOBS,DISP=SHR 


//DYNAMIC 


DD DSN=DIV. SAMPLE, DISP=SHR 


//SYSABEND 
/* 


DD SYSOUT=* 
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Processing a Data-in- Virtual Object. 



The following example shows a program that processes a data-in-virtual object. The first part of 
the program identifies the data set and accesses the object. Then it obtains the virtual storage 
where it will place the window. 



SAMPLE 


CSECT , 


SAMPLE 


AMODE 31 


SAMPLE 


RMODE ANY 


* 


FUNCTION: GETMAIN SOME VIRTUAL STORAGE. THEN 


* 


IDENTIFY AND ACCESS THE LINEAR DATA SET. THEN 


* 


MAP AND PROCESS THE VIRTUAL STORAGE, AND STORE 


* 


naT2\ TMTD TT THPN nO CJOMF QAX/FC; AMD 'RPClp'rpo 
UnXn J-Vi ±\J XX « X n.CiiN LJ\J iJKJlJ'irj Oi^V£iO AINiy I\XjO£iXOa 


* 


FINISH UP WITH AN^ UNMAP, AN UNACCESS AND AN 


* 


UNIDENTIFY. ALL INVOCATIONS OF DATA- IN- VIRTUAL 


* 
* 


IN THIS PROGRAM WILL DEFAULT TO ' RETAIN = NO ' . 


* 


DESCRIPTION: THIS JOB MAKES CHANGES IN THE 


* 


LINEAR DATASET CLUSTER, ' DIV . SAMPLE ' , WHICH IS 


* 


TREATED AS A LINEAR DATASET. AFTER THIS JOB 


* 


IS RUN, THE DATASET WILL CONTAIN SEVEN PAGES 


* 


OF ONES, FOLLOWED BY ONE PAGE OF ZEROES, 


* 


FOLLOWED BY EIGHT PAGES OF FIVES. IT IS 


* 


ASSUMED THE DATASET WAS CREATED BY A DEFINE 


* 


CLUSTER COMMAND AND THAT IT CONTAINS ZEROES 


* 

* 


WHEN THIS PROGRAM BEGINS TO EXECUTE. 


@MAINENT DS OH 




USING *,R15 




B @PROLOG 




DC AL1(14) 




DC C SAMPLE PROGRAM' 




DROP R15 


©PROLOG 


STM R14,R12,12(R13) STD ENTRY LINKAGE 




LR R12,R15 




USING SAMPLE, R12 




ST R13 , SAVEAREA+4 




LR R2,R13 




LA R 13, SAVE AREA 




ST R13,8(R2) 


* 


SR R15,R15 CLEAR R15 


* 
* 


GET STORAGE FOR THE WINDOW 




GETMAIN RU,LV=16*4096,SP=0,BNDRY=PAGE 


* 


ST R1,MAPPTR1 PTR TO STORAGE 


* 
* 


INVOKE IDENTIFY SERVICE OF DIV MACRO 




DIV IDENTIFY , DDNAME=DDNAME , TYPE=DA , ID=TESTID 




LTR R15,R15 CHECK IF RC IS ZERO 


* 


BNZ ERROR IDENTIFY FAILED 


* 
* 


INVOKE ACCESS SERVICE OF DIV MACRO 




DIV ACCESS , MODE=UPDATE , ID=TESTID 




LTR R15,R15 CHECK IF RC IS ZERO 




BNZ ERROR ACCESS FAILED 



100 Supervisor Services and Macro Instructions 



Processing a Data-in-Virtual Object (continued) 



The program maps the object. The resulting virtual storage window is eight pages long, and it 
corresponds to the second eight blocks of the object. The window is situated in the virtual 
storage obtained earlier by the GETMAIN macro. The program fills the window with fives, 
then saves the window back into the second eight blocks of the object. The program eradicates 
the window by invoking UNMAP. 



* INVOKE THE MAP SERVICE OF THE DIV MACRO 

* TO SKIP THE FIRST EIGHT BLOCKS OF THE OBJECT 



L 


R3, EIGHT 


GET SPAN 


ST 


R3 , SPVALUE 


INITIALIZE SPAN 


ST 


R3,0FFS 


INITIALIZE OFFSET 


DIV 


MAP , ID=TESTID , 


AREA=MAPPTR1, 




SPAN=SPVALUE , OFFSET=OFFS 


LTR 


R15 ,R15 


CHECK IF RC IS ZE] 


BNZ 


ERROR 


MAP FAILED 


FILL 


IN 5'S FOR ALL 


EIGHT MAPPED BLOCKS 


L 


R1,MAPPTR1 


POINTS TO WINDOW 


LR 


R2,R1 


POINTS TO MAP 


SR 


R5,R5 


COUNTER 32 KBYTES 


L 


R6, PAGES 


COUNTER MAXIMUM 


IC 


R3,N55 


5S USED AS FILLER 


STC 


R3,0( ,R2) 


STORE INTO MAP 


LA 


R2 , 1( ,R2) 


POINTS NEXT BYTE 


LA 


R5,l( ,R5) 


COUNT UP ONE BYTE 


CR 


R5,R6 


LAST BYTE OF MAP? 


BM 


LOOPl 


DO AGAIN IF NOT 



LOOPl 



* 

* INVOKE THE SAVE SERVICE OF THE DIV MACRO 
* 

DIV SAVE,ID=TESTID,SIZE=OBJSIZE 

LTR R15,R15 CHECK ZERO RC 

BNZ ERROR SAVE FAILED 

* 

* INVOKE THE UNMAP SERVICE OF THE DIV MACRO 
* 

DIV UNMAP, ID=TESTID,AREA=MAPPTR1 
LTR R15,R15 CHECK ZERO RC 

BNZ ERROR UNMAP FAILED 

* 

* OBJECT NOW HAS 8 CONTIGUOUS PAGES OF 5 ' S 

* . 
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Processing a Data-in-Virtual Object (continued) 

The program creates a new window that includes the first eight blocks of the object. This map 
omits OFFSET, causing a default offset of zero to be used with the specified span of eight 
blocks. After filling the window with ones, the program invokes RESET against the eighth 
block of the object, which corresponds to the eighth page of the window. Because the 
information provided by the reset comes from the object, which still contains zeroes, the eighth 
page in the window is set to zeroes. 





INVOKE MAP SERVICE FOR 


FIRST EIGHT 4K 




* 


BLOCKS OF DATASET, WITH 


DEFAULT OFFSET. 






L 


R3, EIGHT 


GET VALUE OF SPAN 






ST 


R3,SPVALUE ' 


INITIALIZE SPAN 






DIV 


MAP , ID=TESTID , AREA=MAPPTR1 , 


X 






SPAN=SPVALUE 








LTR 


R15,R15 


CHECK ZERO RC 




* 


BNZ 


ERROR 


MAP FAILED 




* 


FILL 


IN DATA - I'S FOR 


THE FIRST 8 PAGES 






L 


R1,MAPPTR1 


POINTS TO WINDOW 






LR 


R2 ,R1 


POINTS TO MAP 






SR 


R5 ,R5 


COUNTER 32 KBYTES 






L 


R6, PAGES 


COUNTER MAXIMUM 






IC 


R3 ,N11 


IS USED AS FILLER 






STC 


R3,0( ,R2) 


STORE INTO MAP 






LA 


R2,l( ,R2) 


POINTS TO NEXT BYTE 






LA 


R5,l( ,R5) 


COUNT UP ONE BYTE 






CR 


R5,R6 


LAST BYTE OF MAP? 




* 


BM 


L00P2 


DO AGAIN IF NOT 




* 


RESET 8TH VIRTUAL BLOCK FROM THE CORRESPONDING 




* 


BLOCK ON 


DASD. THIS BLOCK 


NOW CONTAINS ZEROES 




* 


SINCE THE PROGRAM HAS NOT 


YET INVOKED ANY 




* 
* 


SAVE SERVICES AFFECTING IT 








L 


R3, SEVEN 








ST 


R3,0FFS 


INITIALIZE OFFSET 






L 


R3,0NE 








ST 


R3,SPVALUE 


INITIALIZE SPAN 






DIV 


RESET , ID=TESTID , 




X 






SPAN=SPVALUE , OFFSET=OFFS 






LTR 


R15,R15 


CHECK IF RC IS ZERO 






BNZ 


ERROR 


RESET FAILED 
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I Processing a Data-in-Virtual Object (continued) 



The program saves the window in the first eight blocks of the object by issuing the DIV macro, 
specifying SAVE. Then it terminates its use of the object by invoking the UNMAP, 
UNACCESS, and UNIDENTIFY services of the DIV macro. 



* INVOKE SAVE, USING DEFAULTS FOR SPAN AND 

* OFFSET. THIS SAVES * BLOCKS. THE FIRST 

* SEVEN ARE FILLED WITH X'll' AND THE LAST 

* HAS ALL BINARY ZEROES. 

DIV SAVE,ID=TESTID,SIZE=OBJSIZE 

LTR R15,R15 CHECK ZERO RC 

BNZ ERROR SAVE FAILED 

* INVOKE THE UNMAP SERVICE 

DIV UNMAP , ID=TESTiD , AREA=MAPPTR1 

LTR R15,R15 CHECK IF RC IS ZERO 

BNZ ERROR UNMAP FAILED 

* THE OBJECT NOW HAS SEVEN CONTIGUOUS BLOCKS OF 

* I'S, FOLLOWED BY ONE BLOCK OF O'S, FOLLOWED BY 

* EIGHT BLOCKS OF 5'S. NOW INVOKE UNACCESS. 

DIV UNACCESS , ID=TESTID 

LTR R15,R15 CHECK IF RC IS ZERO 

BNZ ERROR UNACCESS FAILED 

* 

* INVOKE THE UNIDENTIFY SERVICE 
* 





B 


EXIT 


SKIP ERROR PROCESSING 


ERROR 


EQU 


* 






L 


R15, SIXTEEN 


BAD RETURN CODE 




ST 


R15,SAVER15 


HOLD R15 VALUE 


EXIT 


EQU 


* 






DIV 


UNIDENTIFY, ID- 


=TESTID 




LTR 


R15,R15 


CHECK IF RC IS ZERO 




BZ 


FREE 


IF SO, LEAVE RC GOOD 




L 


R15, SIXTEEN 


SET BAD RETURN CODE 




ST 


R15,SAVER15 


HOLD R15 VALUE 
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I Processing a Data-in- Virtual Object (continued) 



Finally, the program frees its virtual storage and goes through a standard exit linkage 
sequence. 



* 


FREE STORAGE AND EXIT 


FREE 


EQU * 






FREEMAIN RU , A=MAPPTR1 ,LV=16*4096 , SP=0 




L R15,SAVER15 


RETRIEVE R15 




L R13,4(R13) 


STD EXIT LINKAGE 




L R14,12(R13) 






LM R0,R12,20(R13) 


SAVE RETURN CODE 




BR R14 




* 


SPACE 2 




* 
* 


DECLARE VARIABLES 




MAPPTRl 


DS A 


PTR TO GETMAINED STORAGE 


OBJSIZE 


DS F 


SIZE RETURNED FROM ACCESS 


OFFS 


DS A 


POSITION IN OBJECT 


SPVALUE 


DS A 


LENGTH TO BE MAPPED-RESET 


SAVER 15 


DS F • 0 ' 


RC VALUE IN REG 15 


SAVEAREA DS CL72 


ITQPn RY DATA— TKf— VTRTFTAT. 


TESTID 


DS CL8 


ID RETURNED FROM IDENTIFY 


DDNAME 


DS CL8 






ORG DDNAME 






DC AL1(7) 


LENGTH OF DDNAME 




DC CL7 ' DYNAMIC ' 


NAME USED IN JCL 




ORG DDNAME+8 




* 


SPACE 2 




* 
* 


CONSTANTS 




Nil 


DC X'll' 


HEX ONES 


N55 


DC X'55' 


HEX FIVES 


ONE 


DC F'l' 


ONE 


SEVEN 


DC F'7' 


SEVEN 


EIGHT 


DC F'B' 


EIGHT 


SIXTEEN 


DC F'16' 


SIXTEEN 


PAGES 
* 


DC F'32768' 


8 TIMES 4096 


ie 


REGISTERS 


RO 


EQU 0 




Rl 


EQU 1 




R2 


EQU 2 




R3 


EQU 3 




R5 


EQU 5 




R6 


EQU 6 




R12 


EQU 12 




R13 


EQU 13 




R14 


EQU 14 




R15 


EQU 15 






EJECT 






END SAMPLE 
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I Performance Considerations 



When an application reads more input and writes more output data than necessary, the 
unnecessary reads and writes impact performance. The improved performance that can be 
expected from data-in-virtual comes from a reduction in the amount of unnecessary I/O. 

As an example of unnecessary I/O, consider the I/O performed by an interactive application 
that requires immediate access to several large data sets. The program knows that some of the 
data, although not all of it, will be accessed. However, the program does not know ahead of 
time which data will be accessed. A possible strategy for gaining immediate access to all the 
data is to read all the data ahead of time, reading each data set in its entirety insofar as this is 
possible. Once read into main storage, the data can be accessed quickly. However, if only a 
small percentage of the data is likely to be accessed during any given period, the I/O performed 
on the unaccessed data is unnecessary. 

Furthermore, if the application changes some data in main storage, it might not keep track of 
the changes. Therefore, to guarantee that all the changes are captured, the application might 
then write entire data sets back onto permanent storage even though only relatively few bytes 
are changed in the data sets. 

Whenever such an application starts up, terminates, or accesses different data sets in an 
alternating manner, time is spent reading data that is not likely to be accessed. This time is 
essentially wasted, and the amount of it is proportional to the amount of bypassed data for 
which I/O is performed. Such applications are suitable candidates for a data-in-virtual 
implementation. 

Factors Affecting Performance 

When applications are implemented using the techniques of data-in-virtual, the unnecessary I/O 
does not take place and the performance can be expected to improve. If the same appUcation is 
first implemented using conventional access methods, and then implemented a second time 
using data-in-virtual techniques, the performance differential between the first implementation 
and the second is a combined function of two factors: the size of the data set and its access 
pattern. To obtain significant performance improvements, both factors must be present in the 
application: 

• Pattern refers to the pattern in which the application references the data. If the pattern is 
process-driven, non-pervasive and scattered unpredictably throughout the data set, the 
data-in-virtual implementation will have the better performance. 

• Size refers to the magnitude of the data sets that the application must process. The larger the 
data sets, the more the performance differential between the two implementations, and the 
data-in-virtual implementation will have the better performance. 

Engineering and scientific applications often use data access patterns that are suitable for 
data-in-virtual. Among the appUcations that can be considered for a data-in-virtual 
implementation are: 

• Applications that process large arrays 

• VSAM relative record applications 

• BDAM fixed length record applications 
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On the other hand, commercial applications often use data access patterns that are not suitable 
because they are predictable and sequential. If the access pattern of a proposed application is 
fundamentally sequential or if the data set is small, a conventional VSAM (or other sequential 
access method) implementation may perform better than a data-in-virtual implementation. 
However, this does not rule out commercial applications as data-in-virtual candidates. If the 
performance factors are favorable, any type of application, conmiercial or scientific, is suitable 
for a data-in-virtual implementation. 
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Real Storage Management 



The real storage manager (RSM) administers the use of real storage and directs the movement 
of virtual pages between auxiliary storage and real storage in page size (4096 bytes) blocks. It 
makes all addressable virtual storage in each address space appear as real storage. Only virtual 
pages necessary for program execution are kept in real storage, the remainder reside on 
auxiUary storage. RSM employs the auxiliary storage manager (ASM) of the Data Manager to 
perform the actual paging I/O necessary to transfer pages in and out of real storage. ASM also 
provides DASD allocation and management for paging I/O space on auxiliary storage. RSM 
relies on the system resources manager (SRM) for guidance in the performance of some of its 
operations. 

RSM assigns storage page frames upon request from four pools of available frames, thereby 
associating virtual addresses with real storage addresses. Frames are repossessed upon 
termination of use, when freed by a user, when a user is swapped-out, or when needed to 
replenish an available pool. While a virtual page occupies a real storage frame, the page is 
considered pageable unless specified otherwise as a system page that must be resident in real 
storage. RSM also allocates virtual equals real (V = R) regions upon request by those programs 
that cannot tolerate dynamic relocation. Such a region is allocated contiguously from a 
predefined area of real storage and is non-pageable. Programs in this region do run in 
translation mode, although addressing is one to one virtual to real. 

The paging services provided in MVS/XA include the following: 

• PGRLSE or PGSER, RELEASE parameter - Release the virtual storage contents 

• PGLOAD or PGSER, LOAD parameter - Load the virtual storage areas into real storage 

• PGOUT or PGSER, OUT parameter - Page out the virtual storage areas from real storage 

The page release function allows the user and the system to make available space in both real 
storage and auxiliary storage that is known to be of no future use. Proper use of this function 
can increase the amount of storage available to the system and prevent needless paging I/O 
activity. Usage of page release may improve operating efficiency when the using program can 
discard the contents of a large virtual storage area (circumscribing one or more pages) and 
reuse the virtual storage pages; paging operations may be eliminated for those virtual storage 
pages when they are reused. 

The proper use of the page load and page out functions will tend to decrease system overhead 
resulting from page faults and to clean out of real storage those pages no longer required for 
program execution or not required for some period in the future. 
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Relinquishing Virtual Storage 



When an area of virtual addressable storage within your program no longer has significant 
contents, you can make this storage available by issuing a PGRLSE macro instruction or by 
issuing the PGSER macro instruction with the RELEASE parameter specified. These macro 
instructions make available all real and external page storage wholly associated with the area of 
virtual address space specified. As shown in Figure 41, if the specified addresses are not on 
page boundaries, the low address is rounded up and the high address is rounded down; then, 
the pages contained between the addresses are released. The virtual space remains, but its 
contents are forfeited. When the using program can discard the contents of a large virtual area 
(one or more complete pages) and reuse the virtual space without the necessity of paging 
operations, the page release function may improve operating efficiency. 



1 page 




Released virtual storage 

address 1 address 2 

(low) (high) 



Figure 41. Releasing Virtual Storage 

All storage obtained for your program by the GETMAIN macro instruction is automatically 
freed by the control program when the job step terminates. Freeing storage in this manner 
requires no action on your part. When you issue a FREEMAIN macro instruction, 
FREEMAIN does the equivalent of a page release for any resulting free page and the page is 
no longer available to the issuer. 



Loading/Paging Out Virtual Storage Areas 

The PGLOAD macro instruction and the PGSER macro with the LOAD parameter specified 
essentially provide a page-ahead function. By loading specified virtual storage areas into real 
storage, you can attempt to ensure that certain pages will be in real storage when needed. Page 
faults can occur, however, and these pages may be paged out. 

With the page-load function, you have the option of specifying that the contents of the virtual 
area is to remain intact or be released. If you specify RELEASE = Y, the current contents of 
entire virtual 4K pages to be brought in may be discarded and new real frames assigned without 
page-in operations; if you specify RELEASE =N, the contents are to remain intact and be used 
later. 

If you specify PGLOAD with RELEASE = Y or PGSER with LOAD and RELEASE = Y, the 

page release function will be performed before the page load function. That is, no page-in is 
needed for areas defining entire virtual pages since the contents of those pages are expendable. 

The page-out function initiates page-out operations for specified virtual address pages that are 
in real storage. The real storage frames will be made available for reuse upon completion of 
the page-out operation unless you specify the KEEPREL para];neter in the macro instruction. 
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An area that does not encompass one or more complete pages will be copied to auxiliary 
storage, but the real frames will not be freed. 



Virtual Subarea List (VSL) 

The virtual subarea list provides the basic input to the page service functions that use a 24-bit 
interface: PGLOAD, PGRLSE, and PGOUT. The list consists of one or more doubleword 
entries, each entry describing an area of virtual storage. The Ust must be nonpageable and 
contained in the address space of the subarea to be processed. 

Each parameter list entry has the following format: 

Byte 0 1 2 3 4 5 6 7 

FLAGS START ADDRESS FLAGS END ADDRESS + 1 



Byte 0 Flags: 

Bit 0 (1 ) This bit indicates that bytes 1-3 are a chain pointer to the next VSL entry to be processed; 

bytes 4-7 are ignored. This feature allows several parameter lists to be chained as a single 
logical parameter list. 



Bit 1 


(.1.. 


....) 


Reserved. 


Bit 2 


(..1. 


....) 


Reserved. 


Bit 3 


(...1 


....) 


PGLOAD is to be performed; reserved, set by macro instruction. 


Bit 4 


(.... 


1...) 


PGRLSE is to be performed; reserved, set by macro instruction. 


Bit 5 


(.... 


.1..) 


Reserved. 


Bit 6 


(.... 


..1.) 


Reserved. 


Bit 7 


(.... 


...1) 


Reserved. 



Start Address: 

The virtual address of the origin of the virtual area to be processed. 
Byte 4 Flags: 



BitO 


(1... 


....) 


This flag indicates the last entry of the list. It is set in the last doubleword entry in the list. 


Bit 1 


(.1.. 


....) 


When this flag is set, the entry in which it is set is ignored. 


Bit 2 


(..1. 


....) 


Reserved. 


Bit 3 


(...1 


....) 


This flag indicates that a return code of 4 was issued from a page service function other than 








PGRLSE. 


Bit 4 


(.... 


1...) 


Reserved. 


Bits 


(.... 


.1..) 


PGOUT is to be performed; reserved, set by macro instruction. 


Bit 6 


(.... 


..1.) 


KEEPREL option of PGOUT is to be performed; reserved, set by macro instruction. 


Bit 7 


(.... 


...1) 


Reserved. 



End Address + 1: 

The virtual address of the byte immediately following the end of the virtual area. 



Page Service List (PSL) 

The page services hst provides the basic input to the page service function for the PGSER 
macro instruction. You can specify either 24-bit or 3 1 -bit addresses in the PSL entries. Each 
PSL entry specifies the range of addresses for which a service is to be performed or points to 
the first PSL entry in a new list of concatenated PSL entries that are to be processed. Within a 
PSL entry, you can also nullify a service on a range of addresses by indicating that you do not 
want to perform the service for that range. 
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Each 12-byte PSL entry has the following form: 



Bytes Meaning 

0-3 Bit 0 of byte 0 must be 0. The remainder of these bytes contains the 31 -bit starting address for which the page 
service is to be performed or a pointer to the next PSL. 

4-7 Bit 0 of byte 4 must be 0. If bytes 0-3 contain the starting address, these bytes contain the address of the last 
byte for which the page service is to be performed. If bytes 0-3 contain a pointer to the next PSL, these bytes 
are reserved. 

8 Flags set by the caller as follows: 

Bit Meaning 

0 Set to 1 to indicate that this is the last PSL entry in a concatenation of PSL entries. 

1 Set to 1 to indicate that no services are to be performed for the range of addresses specified. 

2 Set to 1 to indicate that bytes 0-3 contain a pointer to the next PSL. 

9-11 Set by the PGSER service routine. 
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Miscellaneous Services 



Timing Services 

Interval timing is a standard feature of MVS/XA. It provides the ability to request the date 
and time of day and provides for setting, testing, and canceling intervals of time. 

Date and Time of Day 

The operator is responsible for initially supplying the correct date and the time of day in terms 
of a 24-hour clock. You request the date and time of day using the TIME macro instruction. 
The control program returns the date in register 1 and the time of day in register 0 or in a 
doubleword that you supply if you specify the MIC or STCK parameter. 

If ZONE = GMT is specified, the returned time of day and date will be for Greenwich Mean 
Time. If ZONE = LT is specified or if the ZONE parameter is omitted, the local time of day 
and date will be returned. However, if STCK is specified, the ZONE parameter will be 
ignored. 

All references to time of day use the time-of-day (TOD) clock, a 64-bit binary counter. The 
TOD clock runs continuously while the power is on; the clock is not affected by the system 
stop-conditions. The operator normally sets the clock only after an interruption of CPU power 
has caused the clock to stop, and restoration of power has restarted it. The operator sets the 
clock during system initialization in response to a system message. (For more information 
about the TOD clock, see Principles of Operation.) 

Interval Timii^ 

Time intervals up to 24 hours in length can be established for any task in the job step through 
the use of the STIMER or STIMERM SET macro instructions. The time remaining in an 
interval established via the STIMER macro can be tested or cancelled through the use of 
TTIMER macro instruction. The time remaining in an interval estabUshed via the STIMERM 
SET macro instruction can be cancelled or tested through the use of the STIMERM CANCEL 
or STIMERM TEST macro instructions. 

The value of the CPU timer can be obtained by using the CPUTIMER macro instruction. The 
CPU timer is used to track task-related time intervals. 

The TASK, REAL, or WAIT parameters of the STIMER macro instruction and the 
WAIT==YES|NO parameter of the STIMERM SET macro instruction specify the manner in 
which the time interval is to be decreased. REAL and WAIT indicate the interval is to be 
decreased continuously, whether the associated task is active or not. TASK indicates the 
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interval is to be decreased only when the associated task is active. STIMERM SET can 
establish real time intervals only. 

If REAL or TASK is specified on STIMER or WAIT = NO is specified on STIMERM SET, 
the task continues to compete with the other ready tasks for control; if WAIT is specified on 
STIMER, or WAIT = YES is specified on STIMERM SET, the task is placed in a WAIT 
condition until the interval expires, at which time, the task is placed in the ready condition. 

When TASK or REAL is specified on STIMER or WAIT = NO is specified on STIMERM 
SET, the address of an asynchronous timer completion exit routine can also be specified. This 
routine is given control sometime after the time interval completes. The delay is dependent on 
the system's work load and the relative dispatching priority of the associated task. If an exit 
routine is not specified, there is no notification of the completion of the time interval. The exit 
routine must be in virtual storage when specified, must save and restore registers as well as 
return control to the address in register 14. 

Timing services does not serialize the use of asynchronous timer completion routines. 

Figure 42 shows the use of a time interval when testing a new loop in a program. The 
STIMER macro instruction sets a time interval of 5.12 seconds, which is to be decreased only 
when the task is active, and provides the address of a routine called FIXUP to be given control 
when the time interval expires. The loop is controlled by a BXLE instruction. 



LOOP 



STIMER TASK, FIXUP, BINTVL=TIME Set time interval 



TM 
BC 

BXLE 
TTIMER 



TIMEXP,X'01' 
1,NG 

12, 6, LOOP 
CANCEL 



Test if FIXUP routine entered 
Go out of loop if time interval expired 
If processing not complete, repeat loop 
If loop completes, cancel remaining time 



NG 



USING FIXUP, 15 
FIXUP SAVE ( 14 , 12 ) 

01 TIMEXP,X'01' 



Provide addressability 

Save registers 

Time interval expired, set switch in loop 



RETURN ( 14 , 12 ) 



Restore registers 



TIME DC 
TIMEXP DC 



X'00000200' 
X'OO' 



Timer is 5 . 12 seconds 
Timer switch 



Figure 42. Interval Processing 

The loop continues as long as the value in register 12 is less than or equal to the value in 
register 6. If the loop stops, the TTIMER macro instruction causes any time remaining in the 
interval to be canceled; the exit routine is not given control. If, however, the loop is still in 
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effect when the time interval expires, control is given to the exit routine FIXUP. The exit 
routine saves registers and turns on the switch tested in the loop. The FIXUP routine could 
also print out a message indicating that the loop did not go to completion. Registers are 
restored and control is returned to the control program. The control program returns control 
to the main program and execution continues. When the switch is tested this time, the branch 
is taken out of the loop. Caution should be used to prevent a timer exit routine from issuing an 
STIMER specifying the same exit routine. An infinite loop may occur. 

The priorities of other tasks in the system may also affect the accuracy of the time interval 
measurement. If you code REAL or WAIT, the interval is decreased continuously and may 
expire when the task is not active. (This is certain to happen when WAIT is coded.) After the 
time interval expires, assuming the task is not in the wait condition for any other reason, the 
task is placed in the ready condition and then competes for CPU time with the other tasks in 
the system that are also in the ready condition. The additional time required before the task 
becomes active will then depend on the relative dispatching priority of the task. 

The STIMER macro instruction should not be issued while a BTAM OPEN or LINE OPEN 

operation is in progress, since the BTAM OPEN LINE routines also use STIMER. STIMER 
should not be issued before invoking dynamic allocation because dynamic allocation can also 
issue STIMER. 



Communicating with the System Operator 

The WTO and the WTOR macro instructions allow you to write messages to the operator. The 
WTOR macro instruction also allows you to request a reply from the operator. Messages can 
be sent to (and replies received from) as many as 99 operator consoles. Only standard, 
printable EBCDIC characters, shown in Figure 43, appear on the console. All other characters 
are replaced by blanks. If the terminal does not have dual-case capability, it prints lowercase 
characters as uppercase characters. 



Hex 


EBCDIC 


Hex 


EBCDIC 


Hex 


EBCDIC 


Hex 


EBCDIC 


Code 


Character 


Code 


Character 


Code 


Character 


Code 


Character 


40 


(space) 


7B 


# 


99 


r 


D5 


N 


4A 




7C 


@ 


A2 


s 


D6 


0 


4B 




7D 




A3 


t 


D7 


P 


4C 


< 


7E 




A4 


u 


D8 


Q 


4D 


( 


7F 


# 


A5 


V 


D9 


R 


4E 


+ 


81 


a 


A6 


w 


E2 


S 


4F 


1 


82 


b 


A7 


X 


E3 


T 


50 


& 


83 


c 


A8 


y 


E4 


U 


5A 


t 


84 


d 


A9 


z 


E5 


V 


5B 


$ 


85 


e 


CI 


A 


E6 


w 


5C 


* 


86 


f 


C2 


B 


E7 


X 


5D 


) 


87 


g 


C3 


C 


E8 


Y 


5E 


88 


h 


C4 


D 


E9 


z 


5F 


-1 


89 


i 


C5 


E 


FO 


0 


60 




91 


j 


C6 


F 


FX 


1 


61 


/ 


92 


k 


C7 


G 


F2 


2 


6B 


93 


1 


C8 


H 


F3 


3 


6C 


% 


94 


m 


C9 


I 


F4 


4 


6D 




95 


n 


Dl 


J 


F5 


5 


6E 


> 


96 


0 


D2 


K 


F6 


6 


6F 


? 


97 


P 


D3 


L 


F7 


7 


7A 




98 


q 


D4 


M 


F8 


8 














F9 


9 



Figure 43. Characters Printed or Displayed on an MCS Console 
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Notes: 

1. If the display device or printer is defined to JES3, the following characters are also translated 
to blanks: 

I / ; -I ; " 

2. The system recognizes the following hexadecimal representations of the U.S. national 
characters: @ as X'lC; $ as X'5B'; and # as X'7B'. In countries other than the U.S., the 
U.S. national characters represented on terminal keyboards might generate a different 
hexadecimal representation and cause an error. For example, in some countries the $ 
character generates a X'4A '. 

There are two basic forms of the WTO macro instruction: the single-line form, and the 
inultiple-line form. 

The following should be considered when issuing multiple-Une WTO messages (MLWTO). 

• Only the first line of a multiple-line WTO message is passed to the installation-written 
WTO exit routine (lEECVXIT). 

• When a console switch takes place, unended multiple-line WTO messages and multiple-line 
WTO messages in the process of being written to the original console are not moved to the 
new console. 

• When a hard copy switch takes place from the system log to an active operator's console, 
MLWTO messages in the process of being written to the system log are not moved to the 
new hard copy device. 

• The left-most three bytes of register zero must be zero for a multiple-line message. You 
must ensure that this is done. 

• When the system hard copy log is an active operator's console, only the hard copy versions 
of multiple-line messages are written to the console. 

• Because the hard copy log receives a copy of every message in the system, use an active 
operator's console as the hard copy log only in an emergency. 

See the macro instructions section for an explanation of the parameters in the single-line and 
multiple-line forms of the WTO macro instruction. 

The message is routed using the routing codes specified in the WTO macro instruction. At 
system generation, each operator's console in the system is assigned routing codes that 
correspond to the functions that the installation wants that console to perform. When any of 
the routing codes assigned to a message match any of the routing codes assigned to a console, 
the message is sent to that console. 

Disposition of the message is indicated through the descriptor codes specified in the WTO 
macro instruction. Descriptor codes classify WTO messages so that they can be properly 
presented on, and deleted from, display devices. Each WTO macro instruction should contain 
at least one descriptor code. The descriptor code is not printed or displayed as part of the 
message text. 

If the user supplies a descriptor code in the WTO macro instruction, an indicator is inserted at 
the start of the message. The indicators are: a blank, an at sign (@), an asterisk (*), or a blank 
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followed by a plus sign ( + ). The indicator inserted in the message depends on the descriptor 
code that the user supplies and whether the user is a privileged or APF-authorized program or a 
non-authorized problem program. Figure 44 shows the indicator that is used for each 
descriptor code. 



Descriptor Privileged or Non-Authorized 

Code APF-Autfaorized Program Problem Program 

1 * @ 

2 * @ 
3-10 blank blank + 
11 * @ 
12-16 blank blank + 



Figure 44. Descriptor Code Indicators 

The indicator @ or * informs operators that they must take some immediate or critical eventual 
action. A critical eventual action is an action that the operator must perform, as soon as 
possible, in response to a critical situation during the operation of the system. For example, if 
the dump data set is full, the operator is notified to mount a new tape on a specific unit. This 
is considered a critical action because no dumps can be taken until the tape is mounted; it is 
eventual rather than immediate because the system continues to run and processes jobs that do 
not require dumps. 

If a problem program issues a message with descriptor code of 1 or 2, descriptor code 7 is 
forced so that the message is deleted at address space or task termination. For more 
information concerning routing and descriptor codes, see Routing and Descriptor Codes. 

If an application that uses WTO needs to alter a message each time the message is issued, the 
Ust form of the WTO macro may be useful. The message area, which is referenced by the WTO 
parameter list, can be altered before you issue the WTO. The message length, which appears in 
the WTO parameter list, does not need to be altered if you pad out the message area with 
blanks. 

A sample WTO macro instruction is shown in Figure 45. 



Single-line WTO 
format 

Multiple- WTO 
line format 
(list form) 



'BREAKOFF POINT REACHED. 
R0UTCDE=14 ,DESC=7 



TRACKING COMPLETED. 



(•SUBROUTINES CALLED ',C), C 

('ROUTINE TIMES CALLED' ,L) ,(' SUBQUER' ,D) , C 

( 'ENQUER' ,D) ,( 'WRITER' ,D) , C 

( ' DQUER • , DE ) , C 
ROUTCDE= (2,14), DESC= (7,8), MF=L 



Figure 45. Writing to the Operator 

To use the WTOR macro instruction, code the message exactly as designated in the single-line 
WTO macro instruction. (The WTOR macro instruction cannot be used to pass multiple-line 
messages.) When the message is written, the control program adds a two-character message 
identifier before the message to associate the reply with the message. The control program also 
inserts an indicator as the first character of all WTOR messages, thereby informing the operator 
that immediate action is required. You must, however, indicate the response desired. In 
addition, you must supply the address of the area in which the control program is to place the 
reply, and you must indicate the length of the reply. The length of the reply may not be zero. 
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You also supply the address of an event control block which the control program posts after 
the reply has been placed, left-adjusted, in your designated area. 

A sample WTOR macro instruction is shown in Figure 46. The reply is not necessarily 
available at the address you specified until a WAIT macro instruction has been issued. 



XC ECBAD,ECBAD Clear ECB 

WTOR 'STANDARD OPERATING CONDITIONS? REPLY YES OR NO', C 

REPLY , 3 , ECBAD , ROUTCDE= (1 , 15 ) 
WAIT ECB=ECBAD 



ECBAD DC F'O' Event control block 

REPLY DC C'bbb' Answer area 



Figure 46. Writing to the Operator With a Reply 

When a WTOR macro instruction is issued, any console receiving the message has the authority 
to reply. The first reply received by the control program is returned to the issuer of the 
WTOR, providing the syntax of the reply is correct. If the syntax of the reply is not correct, 
another reply is accepted. The WTOR is satisfied when the control program moves the reply 
into the issuer's reply area and posts the event control block. Each console that received the 
original WTOR will also receive the accepted reply unless it's a security message. No console 
receives the accepted reply to a security message. The master console may answer any WTOR, 
even if it did not receive the original message. 



Writing to the Programmer 

The WTO and the WTOR macro instructions allow you to write messages to the programmer, 
as well as to the operator. However, only the operator can reply to a WTOR message. 

To write a message to the programmer, you must specify ROUTCDE =11 in the WTO or the 
WTOR macro instruction. 



Writing to the System Log 

The system log consists of one SYSOUT data set on which the communication between the 
operator and the system is recorded. You can use the system log by coding the information 
that you wish to log in the "text" parameter of the WTL macro instruction. 

When the WTL macro instruction is executed, the control program places your text in one of 
the buffers and, when the buffer is full, writes the buffer onto the system log data set. The 
control program writes the text of your WTL macro instruction on the master console instead 
of on the system log if the system log is not active. 

Although when using the WTL macro instruction you code the message within apostrophes, the 
written message does not contain the apostrophes. The message can include any character that 
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is valid for the WTO macro instruction and is assembled and written the same way as the WTO 
macro instruction. MCS routing codes and descriptor codes are not assigned, since they are not 
needed by the WTL macro instruction. 

Note: The exact format of the output of the WTL macro instruction varies depending on the 
job entry system (JES2 or JES3) that is being used, the output class that is assigned to the log 
at system initiaUzation, and whether DLOG is in effect for JES3. In JES3, system log entries 
are preceded by a 23-character prefix 

that includes a time stamp and routing information. If the combined prefix and message 
exceeds 126 characters, the log entry is split at the first blank or comma encountered when 
scanning backward from the 126th character of the combined prefix and message. See 
Operations: JESS Commands for information about the format of the log entry when using 
JES3. 



Message Deletion 

When using a display console, messages that are no longer necessary can be deleted 
from, the operator's screen by the prograrmner. The control program assigns a message 
identification nimiber to each WTO and WTOR message and returns the message 
identification number in register 1 . The DOM macro instruction uses the identification 
number to indicate which message is to be deleted. The message identification number must 
not be confused with the reply identification number that is assigned to WTOR replies. 

Deleting messages is simphfied by the TOKEN parameter of the DOM, WTO, and WTOR 
macros. TOKEN identifies a unique 4-byte ID that you originate and associate with one or 
more messages when you issue a WTO or WTOR, Then you can use the same token ID when 
you issue a DOM macro to delete all the messages that are associated with the ID. 

When you you want to delete several (up to 60) messages with a single DOM invocation, 
you can use the COUNT parameter with MSGLIST. Coimt is used to indicate the number of 
messages in the message list. The high order bit of each message ID in the message list must 
be zero. 

You can also use the DOM macro instruction to keep WTOR messages from appearing, or 
erase them if they have already appeared, by specifying REPLY = YES on the macro. 
The issuer of the DOM with REPLY = YES must be a task in the same job step and 
address space as the issuer of the WTOR macro instruction or must be a task executing in 
supervisor state, in key 0-7, or authorized by APF. 

Because all outstanding WTOs that were issued with a descriptor code of 7 are deleted at 
address space or task termination, it is possible for a WTO to be deleted without ever being 
displayed. If a task terminates and the JES global processor is not active or if the console to 
which the message is routed is backed up, the message is deleted. 
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You can communicate service requests to the control program using a set of macro instructions 
provided by IBM. These macro instructions are available only when programming in the 
assembler language, and are processed by the assembler program using macro definitions 
supplied by IBM and placed in the macro library when the system was generated. 

The processing of the macro instruction by the assembler program results in a macro expansion, 
generally consisting of data and executable instructions in the form of assembler language 
statements. The data fields are the parameters to be passed to the requested control program 
routine; the executable instructions generally consist of a branch around the data, instructions 
to load registers, and either a branch instruction or a supervisor call (SVC) to give control to 
the proper program. The exact macro expansion appears as part of the assembler output 
listing. 

Applications programmers can use the macro instructions described in this publication without 
restriction. Some macro instructions contain parameters that are restricted to systems 
programmers and installation-approved personnel. These parameters, as well as 
installation-controlled macro instructions, are described in SPL: System Macros and Facilities. 



Selecting the Macro Level 

Certain MVS/XA macro expansions cannot execute on an MVS/370 system. These macros are 
downward incompatible. Parameters that are new for MVS/XA are not supported by the 
MVS/370 versions of the downward incompatible macros. In some cases the new parameters 
are ignored, in other cases they cause assembly errors. Callers executing in 31 -bit addressing 
mode must use the MVS/XA version of these downward incompatible macro instructions. The 
following macro instructions are the downward incompatible macros described in this book: 

• ATTACH 

• ESTAE 

• EVENTS 

• STIMER 

• WTOR 

The SPLEVEL macro instruction solves the problems associated with downward incompatible 
macros. The SPLEVEL macro instruction allows an installation to assemble programs using 
the MVS/XA macro library and to select either the MVS/370 or the MVS/XA version of the 
downward incompatible macros. 

Before issuing a downward incompatible macro, users can specify the macro level that they 
want. They do this by issuing the SPLEVEL macro using the SET=n option, with n-l or 2. 
If n = 1, the MVS/370 expansion of the macro code is generated and if « = 2, the MVS/XA 
expansion of the macro code is generated. If the user does not specify the value of «, the 
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SPLEVEL routine uses the default value of 2. See SPL: System Modifications for information 
concerning the way in which an installation can change this default. 

A user can also select the level of the macro at execution time, based on the system that is 
operating. The example in Figure 47 shows one method of selecting the macro level. The 
example uses the WTOR macro instruction, but any downward incompatible macro instruction 
could be substituted. The code makes use of the fact that the CVTMVSE bit in byte CVTDCB 
(located at offset 116 or X*74' of the communications vector table (CVT)) is set to 1 when 
System Product Version 2 is operating. The CVTMVSE field of the CVT is defined in System 
Product Version 2. 



* DETERMINE WHICH SYSTEM IS EXECUTING 

TM CVTDCB , CVTMVSE 

BO SP2 

* INVOKE MVS/370 VERSION OF THE MACRO 

SPLEVEL SET=1 
WTOR 

B CONTINUE 

* INVOKE MVS/XA VERSION OF THE MACRO 
SP2 SPLEVEL SET=2 

WTOR 

* RESET TO SYSTEM DEFAULT 
CONTINUE SPLEVEL SET 



Figure 47. Macro Level Selected at Execution Time 

The SPLEVEL macro instruction is also described in SPL: System Macros and Facilities. 



Addressing Mode and the Macro Instructions 

Callers in either 24-bit or 31 -bit addressing mode can invoke most of the macros described in 
this book. The following is a list of the macro instructions, documented in Part II of this book, 
that require the caller to be executing in 24-bit addressing mode and require that the parameters 
be located in 24-bit addressable storage: 

• FRACHECK 

• RACHECK 

• RACROUTE 

• RACSTAT 

• SEGLD 

• SEGWT 

• SPIE 

Note: RACF services are also available through the RACROUTE macro, which can execute in 
either 24-bit or 31 -bit addressing mode. 

All addresses specified as parameters for the other macro instructions in this book can be 31 -bit 
addresses unless otherwise stated. If a parameter passed by a program executing in 31 -bit 
addressing mode must be located in 24-bit addressable storage, the restriction is stated in the 
description of the macro instruction. 
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In general, a program executing in 24-bit addressing mode cannot pass parameters located 
above 16 Mb in virtual storage to a system service. There are exceptions to this general rule. 
For example, a program executing in 24-bit addressing mode can: 

• Free storage above 16 Mb using the FREEMAIN macro instruction 

• Allocate storage above 16 Mb using the GETMAIN macro instruction 

• Perform cell pool services for cell pools located in storage above 16 Mb using the CPOOL 
macro instruction 

• Perform page services for storage locations above 16 Mb using the PGSER macro 
instruction 

See the descriptions of the individual macro instructions for details. 

If your program is to execute in 31 -bit addressing mode, you must use the MVS/XA version of 
these macro instructions: 

• ATTACH 

• CALL 

• ESTAE 

• EVENTS 

• LINK 

• SETRP 

• STIMER 

• SYNCH 

• WTOR 

• XCTL 



Macro Instruction Forms 

When written in the standard form, some of the macro instructions result in instructions that 
store into an inline parameter list. The option of storing into an out-of-line parameter list is 
provided to allow the use of these macro instructions in a reenterable program. You can 
request this option through the use of list and execute forms. When Ust and execute forms exist 
for a macro instruction, their descriptions follow the description of the standard form. 

Use the list form of the macro instruction to provide a parameter list to be passed either to the 
control program or to a problem program, depending on the macro instruction. The expansion 
of the list form contains no executable instructions; therefore registers cannot be used in the list 
form. 

Use the execute form of the macro instruction in conjunction with one or two parameter hsts 
estabUshed using the list form. The expansion of the execute form provides the executable 
instructions required to modify the parameter lists and to pass control to the required program. 
Only the ATTACH, LINK, and XCTL macro instructions use two parameter lists: a problem 
program list, resulting from the address parameter and VL parameters, and a control program 
list, resulting from the remaining parameters. The control program list is required, and the 
problem program list is optional in these macro instructions. 
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If you do not generate the control program parameter list form of the macro, you must provide 
the list yourself, initialize it, then update it (either directly or by expUcitly specifying keywords 
on the execute form). 

Note: If the program issuing the execute form of a macro instruction is executing in 24-bit 
addressing mode, the remote control program parameter list must be located in 24-bit 
addressable storage. 

The CALL, DEQ, ENQ, and SNAP macro instructions can result in variable length parameter 
lists. The length of the parameter list generated by the list form of the macro instruction must 
be equal to the maximum length list required by any execute form that refers to the Ust, The 
maximum length Ust can be constructed in one of three methods: 

• Code the parameters required for the maximum length execute form in the list form, 

• Provide a DS instruction immediately following the Ust form to allow for the maximum 
length parameter Ust. 

• Acquire a maximum length list by using commas in the list form to indicate the maximum 
number of parameters. For example, the STORAGE parameter of the SNAP macro 
instruction could be coded as STORAGE = („„„„) to allow for five pairs of addresses. The 
actual addresses would be provided in the execute forms. 

The descriptions of the following macro instructions assume that the standard begin, end, and 
continue columns are used - for example, column 1 is assumed as the begin column. To change 
the begin, end, and continue columns, code the ICTL instruction to estabUsh the coding format 
you wish to use. If you do not use ICTL, the assembler recognizes the standard columns. To 
code the ICTL instruction, see Assembler H Version 2 Application Programming: Language 
Reference. 
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Coding the Macro Instructions 



The table appearing near the beginning of each macro instruction indicates how the macro 
instruction is to be coded. The table does not explain the meanings of the parameters; the 
parameters are explained following the table. 

Figure 48 shows a sample macro instruction, TEST, and summarizes all the coding information 
that is available for it. The table is divided into three columns, A, B, and C. 




name 



b 

TEST 
b 



name: symbol . Begin name in column 1 
One or more blanks must precede TEST. 

One or more blanks must follow TEST. 



^1 



MATH 
HIST 
GEOG 

,Dfi^A=data addr 
,VHG=data length 



data addr: RX-type address, or register (2) - (12) 



data length: symbol or decimal digit, with a maximum 
value of 256. 



,FMT=HEX 
.FMT=DEC 
.FMT=BIN 

,PASS=\^o/t/(? 



Default: FMT=HEX 



value: symbol, decimal digit, or register (1) or (2) - (12). 
Default: PASS=65 



.grade 



grade: symbol, decimal digit, or register (1) or (2) - (12), 



Figure 48. Sample Macro Instruction 

• The first column, A, contains those parameters that are required for that macro instruction. 
If a single line appears in that column, Al, the parameter on that line is required and must 
be coded. If two or more lines appear together, A2, one and only one of the parameters on 
the Unes must be coded. 



• The second column, B, contains those parameters that are optional for that macro 

instruction. If a single line appears in that column, Bl, the parameter on that line is 
optional. If two or more lines appear together, B2, one and only one of the parameters 
appearing on lines may be coded if desired. 

• The third column, C, provides additional information for coding the macro instruction. 
The following terms can appear in column C. 



symbol: any symbol valid in the assembler language. That is, an alphabetic character followed 
by 0-7 alphameric characters, with no special characters and no blanks. 
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decimal digit: any decimal digit up to the value indicated in the parameter description. If both 
symbol and decimal digit are indicated, an absolute expression is also allowed. 

register (2) - (12): one of general registers 2 through 12, specified within parentheses, 
previously loaded with the right-adjusted value or address indicated in the parameter 
description. The unused high-order bits must be set to zero. The register may be designated 
symbolically or with an absolute expression. 

register (0): general register 0, previously loaded as indicated under register (2) - (12) above. 
Designate the register as (0) only. 

register (1): general register 1, previously loaded as indicated under register (2) - (12) above. 
Designate the register as (1) only. 

RX-type address: any address that is valid in an RX-type instruction (for example, LA). 

A-type address: any address that may be written in an A-type address constant. 

default: a value that is used in default of a specified value, and that is assumed if the 
parameter is not coded. 

Use the parameters to specify the services and options to be performed, and write them 
according to the following general rules: 

• If the selected parameter is written in all capital letters (for example, MATH, HIST, or 
FMT=HEX), code the parameter exactly as shown. 

• If the selected parameter is written in italics (for example, grade) substitute the indicated 
value, address, or name. 

• If the selected parameter is a combination of capital letters and italics separated by an 
equal sign (for example, DATA = </ato addr) code the capital letters and equal sign as 
shown, and then make the indicated substitution for the italics. 

• Read the table from top to bottom, and code the parameters in the order shown. Code 
conunas and parentheses exactly as shown. 

• If you select a parameter to be coded, read the third column, C, before proceeding to the 
next parameter. Column C often contains notes pertaining to restrictions on coding the 
parameters. 
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Continuation Lines 

You can continue the parameter field of a macro instruction on one or more additional lines 
according to the following rules: 

1. Enter a continuation character (not blank, and not part of the parameter coding) in column 
72 of the line. 

2. Continue the parameter Held on the next line, starting in column 16. All columns to the 
left of column 16 must be blank. 

You can code the parameter field being continued in one of two ways. Code the parameter 
field through column 71, with no blanks, and continue in column 16 of the next line; or 
truncate the parameter field by a comma, where a comma normally falls, with at least one 
blank before colimm 71, and then continue in column 16 of the next line. Figure 49 shows an 
example of each method. Additional information on the continuation of any assembler 
language macro instruction is provided in the publication Assembler Language. 



1 10 15 44 72 

NAME1 0P1 OPERANDI ,0PERAND2, 0PERAND3,0PERAND4, OPERANDS, 0PERAND6,0PX 
ERAND7 THIS IS ONE WAY 

NAME2 0P2 OPERANDI, 0PERAND2, THIS IS ANOTHER WAY X 

0PERAND3,0PERAND4, ANOTHER x 

OPERANDS, OPERANDS, OPERAND? WAY 



Figure 49. Continuation Coding 
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ABEND — Abnoimally Terminate a Task 



The ABEND macro instruction is used to initiate error processing for a task. ABEND can 
request a full or tailored dump of virtual storage areas and control blocks pertaining to the 
tasks being abnormally terminated, and can specify that the entire job step is to be abnormally 
terminated. Before the task is terminated, an ESTAE exit gets control. This exit may recover 
the task and allow it to retry. 

If the job step task is abnormally terminated or if ABEND specifies job step termination, the 
completion code is recorded on the system output device, and the remaining job steps in the job 
are either skipped or executed as specified in their job control statements. 

If the job step is not to be terminated, the following actions are taken: 

• The task that was active when ABEND was issued is terminated, along with all of the 
subtasks of that active task. 

• The completion code is posted as indicated in the completion code parameter description 
below. 

• The end-of-task exit routine specified in the ATTACH macro instruction that created the 
task which issued ABEND is selected to be given control. The exit routine is given control 
when the originating task of the task for which ABEND was issued becomes active. None 
of the end-of-task exit routines specified for any subtasks of the task for which ABEND 
was issued are given control. 

The ABEND macro instruction is written as follows: 



name 

b 

ABEND 
b 


name: symbol. Begin name in column 1. 
One or more blanks must precede ABEND. 

One or more blanks must follow ABEND. 


con^ code 


comp code: symbol, decimal or hexadecimal digit, or register (1) or (2) - (12). 




Value range: 0 - 4095 


,REASON = reason code 


reason code: symbol, decimal or hexadecimal number, or register (2) - (12). 


,DUMP 


code type: USER or SYSTEM. 


„STEP 


Default: co^ type = USER. 


,„code type 




,DUMP,STEP 




,DUMP„code type 




„STEP,code type 




,DUMP,STEP,co<3fe type 




,DUMPOPT = parm list addr 


parm list addr: RX-type address, or register (2) - (12). 



The parameters are explained as follows: 
comp code 

specifies the completion code associated with the abnormal termination. If the job step is 
to be terminated, the decimal representation of the user completion code or the 
hexadecimal representation of the system completion code is recorded on the system 
output device. If the job step is not to be terminated, the completion code is placed in the 
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TCB of the active task, and in the ECB specified in the ECB parameter of the ATTACH 
macro instruction issued to create the active task. If you specify a hexadecimal digit, you 
must use X'dd' format to distinguish the hexadecimal from decimal. 

,REASON« refl5<7« code 

specifies the reason code that the user wants to pass to subsequent recovery exits. The 
value range for the reason code is a 32-bit hexadecimal number or a 31 -bit decimal 
number. This reason code supplements the completion code associated with an abnormal 
termination, allowing the user to uniquely identify the cause of the abnormal termination. 
The recovery termination manager propagates the reason code to each recovery exit and 
to the TCB and ASCB control blocks, making it available for system messages. 



,DUMP 
„STEP 

mcode type 
,DUMP,STEP 
fDlJMPnCode type 
,,STEP,code type 
,DUMP,STEP,coi/e type 

specifies options available with the ABEND macro instruction: 



DUMP specifies that a dump is requested of virtual storage areas assigned to the task and 
control blocks pertaining to the task. A separate dump is provided for each of the tasks 
being terminated as a result of ABEND. If a //SYSABEND, //SYSMDUMP, or 
//SYSUDUMP DD statement is not provided, the DUMP parameter is ignored. 

STEP specifies that the entire job step of the active task is to be abnormally terminated. 

Note: If the STEP parameter is coded in an ABEND macro under TSO, the TSO job 
will be terminated. 

code type specifies that the completion code is to be treated as a USER or SYSTEM code. 

,DUMPOPT =/;arm list addr 

specifies the address of a parameter list vaUd for the SNAP macro instruction. The 
parameter list is used to produce a tailored dump, and may be created by using the list 
form of the SNAP macro instruction, or a compatible list may be created. The TCB, 
DCB, ID, and STRHDR options available on SNAP will be ignored if they appear in the 
parameter list; the TCB used will be that of the task being terminated, the DCB used will 
be provided by the ABDUMP routine. If a //SYSABEND, //SYSMDUMP, or 
//SYSUDUMP DD statement is not provided, the DUMPOPT parameter is ignored. 

If the dump options specified include ranges of storage areas to be dumped, only the 
storage areas in the first thirty ranges will be dumped. If SUBPLST is specified in the 
SNAP parameter list passed to the ABEND macro instruction via DUMPOPT, the first 
seven subpools will be dumped. 
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Example 1 



Example 2 



Example 3 



Operation: Terminate with a user completion code of 432. 
ABEND 432 



Operation: Terminate with the user completion code that is contained in register 5. The entire 
job step is to be terminated. 

ABEND (5) , ,STEP 

Operation: Terminate with a system completion code of X'0C4'. 
ABEND X • 0C4 ' , , , SYSTEM 
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ATTACH — Create a New Task 



This macro can be assembled compatibly between MVS/XA and MVS/370 through the use of 
the SPLEVEL macro instruction. Default processing will result in an expansion of the macro 
that operates only with MVS/XA. See the topic "Selecting the Macro Level" for additional 
information. If your program is to execute in 31 -bit addressing mode, you must use the 
MVS/XA version of this macro instruction. Except for the address of the DCB, all input 
parameters to the ATTACH macro instruction can have addresses greater than 16 Mb if the 
issuer is executing in 31 -bit addressing mode. 

The ATTACH macro instruction causes the control program to create a new task and indicates 
the entry point in the program to be given control when the new task becomes active. The 
entry point name that is specified must be a member name or an alias in a directory of a 
partitioned data set, or must have been specified in an IDENTIFY macro instruction. If the 
specified entry point cannot be located, the new subtask is abnormally terminated. 

On entry to the attached routine, the high-order bit, bit 0, of register 14 is set to indicate the 
addressing mode of the issuer of the ATTACH macro. If bit 0 is 0, the issuer is executing in 
24-bit addressing mode; if bit 0 is 1, the issuer is executing in 31 -bit addressing mode. 

The address of the task control block for the new task is returned in register 1. The new task is 
a subtask of the originating task; the originating task is the task that was active when the 
ATTACH macro instruction was issued. The limit and dispatching priorities of the new task 
are the same as those of the originating task unless modified in the ATTACH macro 
instruction. 

The load module containing the program to be given control is brought into virtual storage if a 
usable copy is not available in virtual storage. The issuing program can provide an event 
control block, in which termination of the new task is posted, an exit routine to be given 
control when the new task is terminated, and a parameter list whose address is passed in 
register 1 to the new task. If the ECB or ETXR parameter is coded, a DETACH macro 
instruction must be issued to remove the subtask from the system before the program that 
issued the ATTACH macro instruction terminates. If the ECB or ETXR parameter is not 
coded, the subtask is automatically removed from the system upon completion of its execution. 
If the ECB parameter is specified in the ATTACH macro instruction, the ECB must be in 
storage so that the issuer of the attach can wait on it (using the WAIT macro instruction) and 
the control program can post it on behalf of the terminating task. The ATTACH macro 
instruction can also be used to specify that ownership of virtual subpools is to be assigned to 
the new task, or that the subpools are to be shared by the originating task and the new task. 
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The standard forai of the ATTACH macro instruction is written as follows: 


Twme 


name: symbol. Begin name in column 1. 


b 


One or more blanks must precede ATTACH. 


All ACH 




D 


One or more blanks must follow ATTACH. 


El^ — entry name 
EPLOC = entry name addr 
DE = list entry addr 


entry name: symbol. 

entry name addr: A-tj'pe address, or register (2) - (12). 

list entry addr: A-type address, or register (2) - (12). 


,T>C& = dcb addr 


deb addr: A-type address, or register (2) - (12). 


,LPMOD = limit prior mnbr 


limit prior nmbr: symbol, decimal digit, or register (2) - (12). 


jUrMUU — aisp prwr nmor 


disp prior nmbr: symbol, decimal digit, or register (2) - (12). 


,PARAM = (afi?rfr) 

n A n A \/[ t VT — 1 

,r AKAM — yxaar ^, V Jj — 1 


arfifr.- A-type address, or register (2) - (12). 

Note: addr is one or more addresses, separated by commas. For example, 
PARAM = (addr. addr, addr) 


,t,\^a = ecD addr 


ecb addr: A-type address, or register (2) - (12). 


,11 1 AK — a3C« aaar 


exit rtn addr: A-type address, or register (2) - (12). 


,GSPV = subpool nmbr 
,GSPL =subpool list addr 


subpool nmbr: symbol, decimal digit, or register (2) - (12). 
subpool list addr: A-type address, or register (2) - (12). 


,SHSPV = subpool nmbr 
,SHSPL = subpool list addr 


subpool nmbr: symbol, decimal digit, or register (2)-(12). 
subpool list addr: A-type address, or register (2)-(12). 


,SZERO = YES 
,SZERO = NO 


Default: SZERO = YES 


,TASKLIB = rfc^)arfc;r 


deb addr: A-type address, or register (2)-(12). 


,STAI = (ex/Yarfdfr) 

C' 1 ' A T — / /T//x/i* ri/Tx*m /i/i/ifX 
,01/^1 — \^cfA*f uuitr ffHirfn Ciuitrj 

,ESTAI = (ex/Y arfrfr) 

jESTAI = (exit addrparm addr) 


exit addr: A-type address, or register (2)-(12). 


,PURGE = QUIESCE 
PT TR flF = NONF 

,i VJ IVVj Er Jl^ V^l^ d 

,PURGE = HALT 


Note: PURGE may be specified only if STAI or ESTAI is specified, 
npffliilt fnr STAT- PTIRrrF = OITTFSr'F 
Default for ESTAI: PURGE = NONE 


,ASYNCH = NO 
,ASYNCH = YES 


Note: ASYNCH may be specified only if STAI or ESTAI is specified. 
Default for STAI: ASYNCH = NO 
Default for ESTAI: ASYNCH = YES 


,TERM = NO 
,TERM = YES 


Note: TERM may be specified only if ESTAI is specified. 
Default: TERM = NO 


.RELATED = va/Mg 


value: any valid macro keyword specification. 



The parameters are explained as follows: 

= entry name 
EPLOC = entry name addr 
DE = list eritry addr 

specifies the entry name, the address of the entry name, or the address of the name field 
of a 60-byte list entry for the entry name that was constructed using the BLDL macro 
instruction. If EPLOC is coded, the name must be padded to eight bytes, if necessary. 

Note: The task structure must not be changed via an ATTACH or DETACH between 
the issuance of the BLDL and the issuance of the ATTACH for the module, or an abend 
106 with a return code of 15 might result. 

If an unauthorized program issues the ATTACH macro instruction and the DE parameter 
specifies an entry in an authorized library, the program-supplied DE information is 
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ignored for integrity reasons. Instead, contents management uses the BLDL macro 
instruction to construct a new list entry containing the DE information for the ATTACH. 
The DE information supplied by an unauthorized program will also be ignored if the 
ATTACH macro instruction is requesting access to a program or Ubrary that is controlled 
by the System Authorization Facility. 

,DCB = deb addr 

specifies the address of the data control block for the partitioned data set containing the 
entry name described above. (Note: The DCB must be opened before the ATTACH 
macro instruction is executed and must be the DCB used in the BLDL that built the 60 
byte DE list entry. The DCB must remain open until the subtask becomes active, and it 
should not be closed inmiediately following the attach macro.) 

Note: DCB must reside in 24-bit addressable storage. 

jLPMOD = limit prior nmbr 

specifies the number (255 or less) to be subtracted from the current limit priority of the 
originating task. The result is the limit priority of the new task. If this parameter is 
omitted, the current limit priority of the originating task is assigned as the limit priority of 
the new task. 

,DPMOD = disp prior nmbr 

specifies the signed number (255 or less) to be algebraically added to the current 
dispatching priority of the originating task. The result is assigned as the dispatching 
priority of the new task, unless it is greater than the limit priority of the new task. If the 
result is greater, the limit priority is assigned as the dispatching priority. 

If a register is designated, a negative number must be in two's complement form in the 
register. If this parameter is omitted, the dispatching priority assigned is the smaller of 
either the new task's limit priority or the originating task's dispatching priority. 

,PARAM = (addr) 

,PARAM = {addr),YL = 1 

specifies address(es) to be passed to the control program. Each address is expanded inline 
to a fullword on a fullword boundary, in the order designated. Register 1 contains the 
address of the first word when the program is given control. 

VL = 1 should be designated only if the called program can be passed a variable number 
of parameters. VL= 1 causes the high-order bit of the last address to be set to 1; the bit 
can be checked to find the end of the list. 

,^CR=ecb addr 

specifies the address of an event control block for the new task to be used by the control 
program to indicate the termination of the new task. The ECB must be in storage so that 
the issuer of the attach can wait on it (using the WAIT macro instruction) and the control 
program can post it on behalf of the terminating task. The return code (if the task is 
terminated normally) or the completion code (if the task is terminated abnormally) is also 
placed in the event control block. If this parameter is coded, a DETACH macro 
instruction must be issued to remove the subtask from the system after the subtask has 
been terminated. 

jETXR = exit rtn addr 

specifies the address of the end-of-task exit routine to be given control after the new task 
is normally or abnormally terminated. The exit routine is given control when the 
originating task becomes active after the subtask is terminated, and must be in virtual 
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storage when required. If this parameter is coded, a DETACH macro instruction must be 
issued to remove the subtask from the system after the subtask has been terminated. 

The exit routine receives control in the addressing mode of the issuer of the ATTACH 
macro instruction. ATTACH processing issues an ABEND with completion code X*72A' 
if a task attempts to create two subtasks with the same exit routine in different addressing 
modes. 

The contents of the registers when the exit routine is given control are as follows: 



Renter Contents 

0 Control program information. 

1 Address of tibie task control block for the task that was terminated. 
2-12 Unpredictable. 

13 Address of a save area provided by the control program. 

14 Retiutt address (to the control program). 

15 Address of the exit routine. 



The exit routine is responsible for saving and restoring the registers. 

jGSPV = subpool nmbr 

fGSPL -subpool list addr 

specifies a virtual storage subpool number less than 128 or the address of a list of 
virtual storage subpool numbers each less than 128. Except for subpool zero, 
ownership of each of the specified subpools is assigned to the new task. Although it 
can be specified, subpool zero cannot be transferred. When ownership of a subpool is 
transferred, programs of the originating task can no longer GETMAIN or FREEMAIN 
the associated virtual storage areas. 

If GSPL is specified, the first byte of the Ust contains the number of remaining bytes in 
the list; each of the following bytes contains a virtual storage subpool number. 

jSHSPV = subpool nmbr 

,SHSPL = subpool list addr 

specifies a virtual storage subpool number less than 128 or the address of a list of virtual 
storage subpool numbers each less than 128. Programs of both originating task and the 
new task can use the associated virtual storage areas. 

If SHSPL is specified, the first byte of the list contains the number of remaining bytes in 
the list; each of the following bytes contains a virtual storage subpool number. 

,SZERO = YES 
,SZERO = NO 

specifies whether subpool 0 is to be shared with the subtask. YES specifies that subpool 0 
is to be shared; NO specifies that subpool 0 is not to be shared. 

,TAS¥JAli== deb addr 

specifies that a task library DCB address has been supplied and is stored in TCBJLB. 
Otherwise, TCBJLB is propagated from the originating task. (Note: The DCB must be 
opened before the ATTACH macro instruction is executed.) SYSl.LINKLIB is the last 
library searched. If the DCB address specifies SYSl.LINKLIB, the search begins with 
SYSl.LINKLIB, goes through other libraries, and ends with SYSl.LINKLIB. An 806-4 
abend might occur if the requested module is in another library. 

Note: DCB must reside in 24-bit addressable storage. 
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S^Al'^iexit addr) 
,SIAI=(exit addr.parm addr) 
,ESTAI'={exit addr) 
,ES>TAI'^ (exit addr.parm addr) 

specifies whether a STAI or ESTAI SCB is to be created; any STAI/ESTAI SCBs queued 

to the originating task are propagated to the new task. 

The exit addr specifies the address of the STAI or ESTAI exit routine which is to receive 
control if the subtask abnormally terminates; the exit routine must be in virtual storage at 
the time of abnormal termination. The parm addr is the address of a parameter list which 
may be used by the STAI or ESTAI exit routine. 

ATTACH processing passes control to an ESTAI exit routine in the addressing mode of 
the issuer of the ATTACH macro instruction. Therefore, the ESTAI exit routine can 
execute in either 24-bit or 31 -bit addressing mode. A STAI exit routine can execute only 
in 24-bit addressing mode. If a caller in 31 -bit addressing mode specifies the STAI 
parameter on the ATTACH macro instruction, the caller is abended with an X'52A' 
completion code. 

,PURGE = QUIESCE 
,PURGE = NONE 
,PURGE = HALT 

specifies what action is to be taken with regard to I/O operations when the subtask is 
abnormally terminated. No action may be specified (NONE), a halting of I/O operations 
may be requested (HALT), or a quiescing of I/O operations may be indicated 
(QUIESCE). 

,ASYNCH = NO 
^SYNCH = YES 

specifies whether asynchronous exits are to be allowed when a subtask abnormal 
termination occurs. 

ASYNCH = YES must be coded if: 

• Any supervisor services that require asynchronous interruptions to complete their 
normal processing are going to be requested by the ESTAE exit routine. 

• PURGE = QUIESCE is specified for any access method that requires asynchronous 
interruptions to complete normal input/output processing. 

• PURGE = NONE is specified and the CHECK macro instruction is issued in the 
ESTAE exit routine for any access method that requires asynchronous interruptions 
to complete normal input/output processing. 

Note: If ASYNCH = YES is specified and the ABEND was originally scheduled because 
of an error in asynchronous exit handling, an ABEND recursion will develop when an 
asynchronous exit handling was the cause of the failure. 
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,TERM = NO 
,TERM=YES 

specifies whether the exit routine associated with the ESTAI request is also to be 
scheduled in the following situations: 

• CANCEL 

• Forced LOGOFF 

• Job step timer expiration 

• Wait time limit for job step exceeded 

• ABEND condition because incomplete task detached when STAE option not specified 
on DETACH 

• ATTACH macro instruction with the ESTAI operand issued by subtask and attaching 
task abnormally terminates 

,RELATED = va/Me 

specifies information used to self-document macro instructions by 'relating' functions or 
services to corresponding functions or services. The format and contents of the 
information specified are at the discretion of the user, and may be any valid coding 
values. 

The RELATED parameter is available on macro instructions that provide opposite 
services (for example, ATTACH/DETACH, GETMAIN/FREEMAIN, and 
LOAD/DELETE), and on macro instructions that relate to previous occurrences of the 
same macro instructions (for example, CHAP and ESTAE). 

The RELATED parameter may be used, for example, as follows: 

ATTCHl ATTACH EP=MY JOB ,ECB=MYECB ,RELATED= (DETCHl , 

•CREATE SUBTASK' ) 



DETCHl DETACH ( 1 ) , RELATED= ( ATTCHl , ' DETACH SUBTASK ' ) 

Note: The ATTACH macro instruction will fit on one line when coded, so there is no 
need for a continuation indicator. 

When control is returned, register 15 contains one of the following return codes: 



Hexadecimal 




Code 


Meaning 


00 


Successful completion. 


04 


ATTACH was issued in a STAE exit; processing not completed. 


08 


Insufficient storage available for control block for STAI/ESTAI request; processing not completed. 


OC 


Invalid exit routine address or invalid parameter list address specified with STAI parameter; processing 




not completed. 



Note: For any return code other than 00, register 1 is set to zero upon return. 
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Note: The program manager processing for ATTACH is performed under the new subtask, 
after control has been returned to the originating task. Therefore, it is possible for the 
originating task to obtain return code 00, and still not have the subtask successfully created (for 
example, if the entry name could not be found by the program manager). In such cases, the 
new subtask is abnormally terminated. 

Example 1 

Operation: Cause the program named in the list to be attached. Establish RTN as an end of 
task exit routine. 

ATTACH DE=LISTNAME,ETXR=RTN 

Example 2 

Operation: Cause PROGRAM 1 to be attached, share subpool 5, wait on WORDl to 
synchronize processing with that of the subtask, and establish EXITl as an ESTAI exit. 

ATTACH EP=PR0GRAM1 , SHSPV=5 , ECB=W0RD1 , ESTAE= ( EXITl ) 
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ATTACH (List Form) 



Two parameter lists are used in an ATTACH macro instruction: a control program parameter 
list and an optional problem program parameter list. You can construct only the control 
program parameter list in the list form of ATTACH. Address parameters to be passed in a 
parameter list to the problem program can be provided using the list form of the CALL macro 
instruction. This parameter list can be referred to in the execute form of ATTACH. 



The list form of the ATTACH macro instruction is written as follows: 


name 


name: symbol. Begin tuane in column 1. 


b 


One or more blanks must precede ATTACH. 


ATTACH 




b 


One or more blanks must follow ATTACH. 


EP = entry name 
EPLOC = entry name addr 
DE = list entry addr 


entry name: symbol. 

entry name addr: A-type address. 

list entry addr: A-type address. 


,DCB== deb addr 


deb addr: A-type address. 


jLPMOD = limit prior nmbr 


limit prior nmbr: symbol or decimal digit. 


,DPMOD = disp prior nmbr 


disp prior nmbr: symbol or decimal digit. 


,ECB=ffc6 addr 


ecb addr: A-type address. 


,ETXR = exit rtn addr 


exit rtn addr: A-type address. 


,GSPW ^subpool nmbr 
,GSPL =std>pool list addr 


subpool nmbr: symbol or dedmal digit. 
subpool list addr: A-type address. 


,SHSPV = subpool nmbr 
,SHSPL = subpool list addr 


subpool nmbr: symbol or decimal digit. 
subpool list addr: A-type address. 


,SZERO = YES 

,SZERO = NO 


Default: SZERO=YES 


,TASKLIB = rfc/»a</</r 


deb addr: A-type address. 


JSTAl = (exit addr) 

,STAI = (exit addr,parm addr) 

,ESTAI = (eA:i7 addr) 


exit addr: A-type address. 
parm addr: A-type address. 


,PURGE = QUIESCE 
,PURGE = NONE 
.PURGE = HALT 


Note: PURGE may be specified only if STAI or ESTAI is specified. 
Default for STAI: PURGE = QUIESCE 
Default for ESTAI: PURGE = NONE 


,ASYNCH=NO 
.ASYNCH = YES 


Note: ASYNCH may be specified only if STAI or ESTAI is specified. 
Default for STAI: ASYNCH = NO 
Default for ESTAI: ASYNCH = YES 


.TERM = NO 
.TERM = YES 


Note: TERM may be specified only if ESTAI is specified. 
Default: TERM NO 


.RELATED = vfl/Me 


value: any valid macro keyword specification. 


,SF=L 





The parameters are explained under the standard form of the ATTACH macro instruction, with 
the following exception: 

,SF = L 

specifies the list form of the ATTACH macro instruction. 
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ATTACH (Execute Form) 



Two parameter lists are used in ATTACH: a control program parameter list and an optional 
problem program parameter list. Either or both of these parameter lists can be remote and can 
be referred to and modified by the execute form of ATTACH. If only the problem program 
parameter list is remote, parameters that require use of the control program parameter Ust 
cause that list to be constructed inline as part of the macro expansion. 

The execute form of the ATTACH macro instruction is written as follows: 





name 


name: symbol. Begin name in column 1. 


b 






ATTACH 




b 




One or more blanks must follow ATTACH. 


EP^ entry name 
EPLOC = entry name addr 
DE = list entry addr 


entry name: symbol. 

fintrv fiiifktp /liiiiT* R*V»tvn^ sHHrp^^ or r^o't^ter Cy\ - 

list entry addr: RX-type address, or register (2) - (12). 




X>CB = deb addr 


deb addr: RX-type address, or register (2) - (12). 




,LPMOD = limit prior nmbr 


limit prior nmbr: symbol, decimal digit, or register (2) - (12). 




,DPMOD = disp prior nmbr 


disp prior nmbr: symbol, decimal digit, or register (2) - (12). 




,PARAM = (addr) 
,PARAM = laddr),yL = 1 


addr: RX-type address, or register (2) - (12). 

Note: addr is one or more addresses, separated by commas. For example, 
PARAM = (addr. addr. addr) 




,ECB = ecb addr 


cob addr: RX-type address, or register (2) - (12) . 




,ETXK= exit rtn addr 


exit rtn addr: RX-type address, or register (2) - (12). 




,GSPV = subpool nmbr 
,GSPL= subpool list addr 


subpool nmbr: symbol, dedmal digit, or register (2) - (12). 
subpool list addr: RX-type address, or register (2) - (12). 




,SHSPV = subpool nmbr 
,SliSPL= subpool list addr 


subpool nmbr: symbol, decimal digit, or register (2) - (12). 
subpool list addr: RX-type address, or register (2) - (12). 




,SZERO = YES 
,SZERO=NO 






,TASKLIB = </c6a</<^ 


deb addr: RX-type address, or register (2) - (12). 




,STAl = (exit addr) 

,STAI = (exit addr,parm addr) 

,ESTA1 = (exit addr) 

,ESTAI = (exit addr,parm addr) 


exit addr: RX-type address, or register (2) - (12). 
parm addr: RX-type address, or register (2) - (12). 




,PURGE = QUIESCE 
.PURGE = NONE 
.PURGE = HALT 


Note: PURGE may be specified only if SfTAI or ESTAI is specified. 




,ASYNCH = NO 
,ASYNCH = YES 


Note: ASYNCH may be specified only if STAI or ESTAI is specified. 




.TERM = NO 
.TERM = YES 


Note: TERM may be specified only if ESTAI is specified. 




.RELATED = va/«« 


value: any valid macro keyword specification. 


,MF 

,SF = 
,MF 


= (E^rob addr) 
= (E,ctrladdr) 

= (Ejtrob addr)fSF = (E,ctrl addr) 


prob addr: RX-type address, or register (1) or (2) - j(12). 
Ctrl addr: RX-type address, or register (2) - (12) or (1^. 
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The parameters are explained under the standard form of the ATTACH macro instruction, with 
the following exceptions: 

MP = (£'^prob addr) 
,SF {E,ctrl addr) 

,MF = (E,;7roZ) addr),SF^(E,ctrl addr) 

specifies the execute form of the ATTACH macro instruction using either a remote 
problem program parameter list or a remote control program parameter Hst. Any 
problem program or control program parameters are provided in parameter lists expanded 
inline. 

Notes: 

1. If STAI is specified on the execute form, the following fields are overlaid in the control 
program parameter list: exit addr, parm addr, PURGE, and ASYNCH. If parm addr is not 
specified, zero is used; if PURGE or ASYNCH are not specified, defaults are used, 

2. If ESTAI is specified on the execute form, then the following fields are overlaid: exit addr, 
parm addr, PURGE, ASYNCH, and TERM. If parm addr is not specified, zero is used; if 
PURGE, ASYNCH, or TERM are not specified, defaults are used. 

3. If the STAI or ESTAI is to be specified, it must be completely specified on either the list or 
execute form, but not on both forms. 

4. If SZERO is not specified on the list or execute form, the default is SZERO= YES. If 
SZERO = NO is specified on either the list form or a previous execute form using the same 
SE=list, then SZERO = YES is ignored for any following execute forms of the macro. Once 
SZERO = NO is specified, it is in effect for all users of that list. 
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CALL Pass Control to a Control Section 



If your program is to execute in 31 -bit addressing mode, you must use the MVS/XA version of 
this macro instruction. You cannot use the CALL macro instruction to pass control to a 
program in a different addressing mode. 

The CALL macro instruction passes control to a control section at a specified entry point as 
follows: 

• OVERLAY: The overlay segment containing the designated entry point is brought into 
virtual storage if required, and control is passed to the segment. 

Refer to Linkage Editor and Loader for details on overlay. The CALL macro instruction 
cannot be used in an asynchronous exit routine. 

• NON-OVERLAY: If a symbol is designated, the hnkage editor includes the load module 
containing that entry point in the same load module containing the CALL instruction. 
When the CALL macro instruction is executed, control is passed to the control section at 
the specified entry point. 

The Unkage relationship estabUshed when control is passed is the same as that created by a 
BAL instruction; that is, the issuing program expects control to be returned. The control 
program is not involved in passing control, so the reusabihty of the called program must be 
maintained by the user. 

An address parameter Ust can be constructed and a calling sequence identifier can be provided. 
The standard form of the CALL macro instruction is written as follows: 



name 


name: symbol. Begin name in column 1. 


b 


One or more blanks must precede CALL. 


CALL 




b 


One or more blanks must follow CALL. 


entry name 


entry name: symbol or register (15). 


,{addr) 
Xaddr),YL 


addr: A-type address, or register (2) - (12). 

Note: addr is one or more addresses, separated by conmias. For example, 
(addr. addr. addr) 


,ID = id nmbr 


id nmbr: symbol or decimal digit, with a maximum value of 4095. 



The parameters are explained as follows: 
entry name 

specifies the entry name to be given control. 

,(addr) 
,{addr%\L 

specifies address(es) to be passed to the control program. Each address is expanded inline 
to a fuUword on a fullword boundary, in the order designated. Register 1 contains the 
address of the first parameter when the program is given control. (If this parameter is not 
coded, register 1 is not altered.) 
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VL should be coded only if the called program can be passed a variable number of 
parameters. VL causes the high-order bit of the last address parameter to be set to 1; the 
bit can be checked to find the end of the list. 

JD^'id nmbr 

specifies an identifier useful for debugging purposes only. The last fuUword of the macro 
expansion is a NOP instruction containing the identifier value in bytes 3 and 4. 

Upon entry to the called program, the register contents are as follows: 
Reg^ter Meaning 

1 Address of parameter list, if present. 

14 Return address. 

15 Entry address of called program. 

Example 1 

Operation: Call the entry point contmned in register 15, and pass three addresses to the control 
program. 

CALL ( 15 ) , ( ADDRl , ADDR2 , ADDR3 ) 
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CALL (List Fomi) 



The list form of the CALL macro instruction is used to construct a nonexecutable problem 
program parameter list. This list form generates only ADCONs of the address parameters. 
This problem program parameter list can be referred to in the execute form of a CALL, LINK, 
ATTACH, or XCTL macro instruction. 

The list form of the CALL macro instruction is written as follows: 



name 


name: symbol. Begin name in column 1. 


b 


One or more blanks must precede CALL. 


CALL 




b 


One or more blanks must follow CALL. 


,(addr) 
,(<w/</r),VL 


addr: A-type address. 

Note: addr is one or more addresses, separated' by commas. For example, 
(addr, addr, addr) 


,MF = L 





The parameters are explained under the standard form of the CALL macro instruction, with the 
following exception: 

,MF = L 

specifies the list form of the CALL macro instruction. 
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CALL (Execute Form) 



A remote problem program parameter list is referred to and can be modified by the execute 
form of the CALL macro instruction. Only executable instructions and a VCON of the entry 
point are generated. 

The execute form of the CALL macro instruction is written as foUowis: 



name 


name: symbol. Begin name in column 1. 


b 


One or more blanks must precede CALL. 


CALL 




b 


One or more blanks must follow CALL. 


entry name 


entry name: symbol or register (15). 


,iaddr) 
,iaddr),WL 


addr: RX-type address, or register (2) - (12). 

Note: addr is one or more addresses, separated by commas. For example, 
{addr, ad^, addr) 


,ID = id nmbr 


id nmbr: symbol or decimal digit, with a maximum value of 4095. 


MP=(fijfi'obaddr) 


prob addr: RX-type address, or register (1) or (2) - (12). 



The parameters are explained under the standard form of the CALL macro instruction, with the 
following exception: 

,MF = (E,/?ro6 addr) 

specifies the execute form of the CALL macro instruction. This form uses a remote 
problem program parameter list. If the address parameters are also specified in this form, 
the ADCONS of the parameter are placed on contiguous fuUword boundaries beginning 
at the address specified in the MF parameter, and sequentially overlaying corresponding 
fuUwords in the existing list. 
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CHAP — Change Dispatching Priority 



CHAP changes the dispatching priority of the task or any of its subtasks relative to the other 
tasks in the address space. It does not change the priority relative to other tasks in the system. 
CHAP may also change the limit priority of a subtask. (See the section "Priorities" in this 
publication.) The algebraic sum of the priority value arid the dispatching priority of the subject 
task determines the new dispatching priority. 

• If the subject task is the task executing CHAP, its dispatching priority is set equal to the 
sum of the priority value and the dispatching priority. This value is not set at less than 
zero or greater than the Umit priority for the task. Its limit priority is unaffected. 

• If the subject task is a subtask of the task executing CHAP, its dispatching priority is set 
equal to the sum of the priority value and the dispatching priority. This value is not set at 
less than zero or greater than the limit priority of the task executing CHAP. After this 
modification, if the subtask's dispatching priority exceeds its limit priority, the limit priority 
is made equal to the dispatching priority. 

The CHAP macro instruction is written as follows: 



name 


name: symbol. Begin name in column 1. 


b 


One or more blanks must precede CHAP. 


CHAP 




b 


One or more blanks must follow CHAP. 


priority value 


priority value: sjmbol, decimal digit, or register (0) or (2) - (12). 


,'S' 


tcb addr: RX-type address, or register (1) or (2) - (12). 


,tcb addr 


Default: 'S' 


.RELATED = va/i<e 


value: any valid macro keyword specification. 



The parameters are explained as follows: 
priority value 

specifies the signed value to be added to the dispatching priority of the specified task. If 
the value is negative and contained in a register, it must be in two's complement form. 

,'S' 

ftcb addr 

specifies the address of a fuUword on a fuUword boundary containing the address of a 
task control block (TCB) for a subtask of the active task. If 'S' is coded or assumed, the 
dispatching priority of the active task is updated. 

Note: TCB must reside in 24-bit addressable storage. 

,RELATED = va/i/e 

specifies information used to self-document macro instructions by 'relating' functions or 
services to corresponding functions or services. The format and contents of the 
information specified are at the discretion of the user and may be any valid coding values. 

The RELATED parameter is available on macro instructions that provide opposite 
services (for example, ATTACH/DETACH, GETMAIN/FREEMAIN, and 
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LOAD/DELETE), and on macro instructions that relate to previous occurrences of the 
same macro instructions (for example, CHAP and ESTAE). 



The RELATED parameter may be used, for example, as follows: 
CHAPUP CHAP 1, 'S' ,RELATED=(CHAPDOWN, 'UP PRIORITY') 

CHAPDOWN CHAP -1, 'S' ,RELATED=(CHAPUP, 
. ' RESUME INITIAL PRIORITY ' ) 

Note: The second CHAP macro instruction will fit on one line when coded, so there is 
no need for a continuation indicator. 

Example 1 

Operation: Lower by 2 the dispatching priority of the subtask TCB, whose address is in a 
fuUword which is addressed by register 1. The subtask TCB will be repositioned on the 
dispatching queue in accordance with its new dispatching priority. 

CHAP -2,(1) 

Example 2 

Operation: Cause the TCB of the task issuing CHAP to be repositioned at the bottom of the 
group of TCBs on the dispatching queue for the address space, having the same dispatching 
priority as that task. 

CHAP 0 
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— Perform Cell Pool Services 



The CPOOL macro instruction creates a cell pool, obtains or returns a cell to the cell pool, or 
deletes the previously built cell pool, according to the function requested. Problem state, 
non-system key users cannot create cell pools in subpools greater than 127. On entry to the 
CPOOL macro instruction, users who specify the parameters: BUILD, DELETE, or 
REGS = SAVE must pass the address of a 72-byte save area in register 13. 

The CPOOL macro instruction is written as follows: 



name 


name: symbol. Begin name in coliunn 1. 


b 


One or more blanks must precede CPOOL. 


CPOOL 




b 


One or more blanks must follow CPOOL. 


BUILD 
GET 
FREE 
DELETE 




,UNCOND 

,u 

,COND 

,c 


Default: UNCOND 

Note: This parameter can be specified only with the GET keyword. 


,PCELLCT=/)rimary cell count 


cell count: symbol, decimal digit, or register (0), (2) - (12). 

IVote: This parameter can be specified only with the BUILD keyword. 


,SCEmjT = secondary cell count 


Default: PCELLCT 

Note: This parameter can be specified only with the BUILD keyword. 


,CSIZE = cell size 


cell size: symbol, decimal digit, or register (0), (2) - (12). 

Note: This parameter can be specified only with the BUILD keyword. 


,SP =subpool number 


subpool number: symbol, decimal digit 0-127, or register (0), (2) - (12). 
Note: This parameter can be specified only with the BUILD keyword. 
Default: SP=0 


,LOC = BELOW 
,LOC = (BELOW,ANY) 
,LOC = ANY 
,LOC = (ANY,ANY) 
,LOC = RES 
,LOC = (RES,ANY) 


Default: LOC = RES 

Note: This parameter can be specified only with the BUILD keyword. 


,CPID= pool id 


pool id: RX-type address or register (0), (2) - (12). 

Note: This parameter must be specified with the GET, FREE, and DELETE 
keywords but is optional with the BUILD kejrword. 


,CELL = celladdr 


cell addr: RX-type address or register (2) - (12). 

Note: This parameter is required with the FREE keyword, is optional with the 
GET keyword, and cannot be specified with the BUILD and DELETE 
keywords. 


,HDR = Mr 


hdr: character string enclosed in single quotes, RX-type address, or register 
(0),(2)-(12). 

Default: 'CPOOL CELL POOL' 

Note: This parameter can be specified only with the BUILD keyword. 


,REGS=SAVE 
,REGS = USE 


Default: REGS = SAVE 

Note: This parameter can be specified only with the GET or FREE keywords. 
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The parameters are explained as follows: 



BUILD 
GET 
FREE 
DELETE 

specifies the cell pool service to be performed. 

BUILD creates a cell pool in a specified subpool by allocating storage and chaining the 
cells together. It returns an identifier (CPID) to be used with GET, FREE, and DELETE 
requests. Therefore, BUILD must be done before GET, FREE, or DELETE. 

GET attempts to obtain a cell from the previously built cell pool. This request can be 
conditional or unconditional as described under the UNCOND/COND keyword. 

FREE returns a cell to the cell pool. 

DELETE deletes a previously built cell pool and frees storage for the initial extent, all 
secondary extents, and all pool control blocks. 

,UNCOND 
,U 

,COND 
,C 

when used with GET specifies whether the request for a cell is conditional or 
unconditional. If COND or C is specified and the cell pool is empty, the CPOOL service 
routine returns to the caller without a cell and places a zero in the return field of the cell 
address. If UNCOND or U is specified and the cell pool is empty, the CPOOL service 
routine extends the pool in order to obtain a cell for the caller. 

^CELLCT= primary cell count 

specifies the number of cells expected to be needed in the initial extent of the cell pool. 
The CPOOL service module uses PCELLCT and cell size, (CSIZE) to determine the 
optimum niunber of cells to provide in order to make effective use of virtual and real 
storage. 

fSCELLVT = secondary cell count 

specifies the number of cells expected to be in each secondary or non-initial extent of tiie 
cell pool. The CPOOL service routine uses SCELLCT and CSIZE to determine the 
optimum number of cells to provide in order to make effective use of virtual and real 
storage. 

,CSIZE = ce// j/ze 

specifies the number of bytes in each cell of the cell pool. If CSIZE is a multiple of 8, the 
cell resides on doubleword boundaries. If CSIZE is a multiple of 4, the cell resides on 
word boundaries. The minimum value of CSIZE is 4 bytes. 

,SP = subpool number 

specifies the subpool from which the cell pool is to be obtained. If a register or variable is 
specified, the subpool number is taken from bits 24-31. 
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,LOC=BELOW 
,LOC = (BELOW,ANY) 
,LOC=ANY 
,LOC = (ANY,ANY) 
,LOC = RES 
,LOC = (RES,ANY) 

specifies the location of virtual storage and real storage for the cell pool. 

Note: The location of real storage using this parameter is only guaranteed after the 
storage is fixed. 

LOC = BELOW indicates that virtual and real storage are to be allocated below 16 Mb. 

LOC = (BELOW, ANY) indicates that virtual storage is to be allocated below 16 Mb and 
real storage can be anywhere. 

LOC = ANY and LOC = (ANY, ANY) indicate that both virtual and real storage can be 
located anywhere. 

LOC = RES indicates that the location of virtual and real storage depends on the location 
of the issuer of the macro. If the issuer resides below 16 Mb, virtual and real storage are 
allocated below 16 Mb; if the issuer resides above 16 Mb, virtual and real storage can be 
located anywhere. 

LOC = (RES, ANY) indicates that the location of virtual storage depends on the location 
of the issuer of the macro. If the issuer resides below 16 Mb, virtual storage is allocated 
below 16 Mb; if the issuer resides above 16 Mb, virtual storage is allocated anywhere. 
Real storage can be located anywhere. 

Note: Callers executing in 24-bit addressing mode could perform BUILD request services 
for cell pools located in storage above 16 Mb by specifying LOC = ANY or 
LOC = (ANY,ANY). 

,C^JD=poolid 

specifies the address or register containing the cell pool identifier that is returned to the 

caller after the pool is created using CPOOL BUILD. The issuer must specify CPID on 
all subsequent CPOOL requests containing the keywords GET, FREE, or DELETE. 

,CELL = cell addr 

specifies the address or register where the cell address is returned to the caller on a GET 
or FREE request. 

,HDR = Mr 

specifies a 24-byte header, which is placed in the header of each initial and secondary 
extent. The header can contain user-supplied information that would be useful in a 
dump. 

,REGS = SAVE 
,REGS = USE 

indicates whether or not registers 2-12 are to be saved. If REGS = SAVE is specified, the 
registers are saved in a 72-byte user-supplied save area pointed to by register 13. If 
REGS = USE is specified, the registers are not saved. 
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The contents of the registers on return from this macro depends on the parameters specified. 
Register(s) Comment 

0 Contains the cell pool identification (CPID) 

1 Contains the address of the cell that was obtained if GET was specified; contains zero if GET conditional 
was specified and the cell could not be obtained 

2-12 Saved for BUILD and DELETE requests or if REGS = SAVE is specified 

S-13 Saved if GET conditional or FREE is specified with REGS = USE 

13 Saved if GET unconditional and REGS = USE, BUILD, or DELETE is specified 

Example 1 

Operation: Create a cell pool containing 40-byte cells from subpool 2. Allow for 10 cells in the 
initial extent and 20 cells in all subsequent extents of the cell pool. 

CPOOL BUILD , PCELLCT=10 , SCELLCT=20 , CSIZE=40 , SP=2 

Example 2 

Operation: Unconditionally obtain a cell pool, specifying the pool ID in register 2. Do not 
save the registers. 

CPOOL GET , U , CPID= {2) , REGS=USE 

Example 3 

Operation: Free a cell specifying the pool ID in register 2 and the cell address in register 3. 

CPOOL FREE , CP I D= ( 2 ) , CELL= (3 ) 

Example 4 

Operation: Delete a cell pool, specifying the pool ID in register 2. 
CPOOL DELETE, CP ID= (2) 
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CPOOL - (List Form) 



The list form of the CPOOL macro instruction builds a non-executable parameter hst that can 
be referred to by the execute form of the CPOOL macro. 

The Ust form of the CPOOL macro instruction is written as follows: 



name 


name: symbol. Begin name in column 1 . 


b 


One or more blanks must precede CPOOL. 


CPOOL 




b 


One or more blanks must follow CPOOL. 


BUILD 




,FCELLCT= primary cell count 


cell count: symbol, decimal digit, or register (0), (2) - (12). 

Note: PCELLCT must be specified on either the list or the execute form of the 

macro. 


,SCELLCT= secondary cell count 


Default: PCELLCT 


,CS1ZE = cell size 


cell size: symbol, decimal digit, or register (0), (2) - (12). 

Note: CSIZE must be specified on either the list or the execute form of the 

macro. 


,SP = subpool number 


subpool number: symbol, decimal digit 0-127, or register (0), (2) - (12). 
Default: SP = 0 


,LOC = BELOW 
,LOC = (BELOW,ANy) 
,LOC = ANY 
,LOC = (ANY,ANY) 
,LOC = RES 
,LOC = (RES,ANY) 


Default: LOC = RES 


,CVID= pool id 


pool id: A-type address or register (0), (2) - (12). 


,HDR=/jrfr 


hdr: character string enclosed in single quotes, A-type address, or register (0), 
(2) - (12). 


,MF = L 





The parameters are explained under the standard form of the CPOOL macro instruction with 
the following exception: 

,MF = L 

specifies the Ust form of the CPOOL instruction. 
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CPOOL — (Execute Form) 



The execute form of the CPOOL macro instruction is written as follows: 



name 


name: symbol. Begin name in column 1. 


b 


One or more blanks must precede CPOOL. 


CPOOL 




b 


One or more blanks must follow CPOOL. 


BUILD 




,PCELLCT=/>rH«flrj; cell count 


cell count: symbol, decimal digit, or register (0), (2) - (12). 

Note: PCELLCT must be specified on either the list or the execute form of the 

macro. 


,^CELLCT = secondary cell count 


Default: PCELLCT 


,CSIZE = cell size 


cell size: symbol, decimal digit, or register (0), (2) - (12). 

Note: CSIZE must be specified on either the list or the execute form of the 


,SP = subpool number 


subpool number: symbol, decimal digit 0-127, or register (0), (2) - (12). 
Default: SP = 0 


,LOC = BELOW 
,LOC = (BELOW,ANY) 
,LOC = ANY 
,LOC = (ANY,ANY) 
,LOC = RES 
,LOC = (RES^NY) 


Default: LOC = RES 


,CFlD=pool id 


pool id: RX-type address or register (0), (2) - (12). 


,HDR = AdSr 


hdr: character string enclosed in single quotes, RX-type address, or register 
(0),(2)-(12). 


MP = (E,ctrlprog) 


Ctrl prog: RX-type address or register (0) - (12). 



The parameters are explained under the standard form of the CPOOL macro instruction with 
the following exception: 

iMF = (^,ctrl prog) 

specifies the execute form of the CPOOL instruction. 
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— Provide Current CPU Timer Value 



The CPUTIMER macro instruction provides the current CPU timer value for this processor. 
This value consists of the time remaining in a time interval established by the STIMER macro 
instruction. If there is no outstanding time interval, the value returned by the macro 
instruction is meaningless. 

The caller of the CPUTIMER macro instruction must provide the address of a 72-byte save 
area in register 13. 

The CPUTIMER macro instruction is written as follows: 



name 


name: symbol. Begin /lome in column 1. 


b 


One or more blanks must precede CPUTIMER. 


CPUTIMER 




b 


One or more blanks must follow CPUTIMER. 


TV^tor addr 


DeEndt: TU 


MlC^tor addr 


stor addr: RX-type address, or register (1), (2) - (12). 


,ERRET= err rtn addr 


err rtn addr: RX-type address, or register (2) - (12). 



The parameters are explained as follows: 

T\],stor addr 
'MlCyStor addr 

specifies the form in which the remaining time interval is to be returned to the caller. 
This value is returned as an unsigned 64-bit binary number, at the address specified by 
stor addr. stor addr must be the start of a double word area on a double word boundary 
and it must be a 31 -bit address. 

If TU is specified, the timer value is returned to the caller in timer units. The low-order 
bit of the timer value is approximately equal to 26.04166 microseconds (one timer unit). 

If MIC is specified, the timer value is returned to the caller in microseconds. Bit 51 of the 
timer value is equivalent to 1 microsecond. 

The resolution of CPU timer is model dependent. See Principles of Operation for a 
description of the CPU timer. 

,ERR£T = err rtn addr 

specifies the 31 -bit address of the routine to be given control when the CPUTIMER 
function cannot be performed. If this parameter is omitted, the CPUTIMER function 
returns a code in general register 15 indicating why the function could not be performed. 
The error routine executes in the addressing mode of the issuer of the CPUTIMER macro 
instruction. 
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The return codes are as follows: 



Example 1 



Example 2 



Example 3 



Example 4 



Hexadecimal 

Code Meaning 

0 The function was performed. 

4 The function was not performed because the user-specified area was not on a double word boundary. 

8 The function was not performed because the user supplied an invalid address. 

OC The function was not performed because the value of the CPU timer was not usable. 

10 The function was not performed because a machine check occurred. 

14 The function was not performed because a prograiQ check occurred. 



Operation: Place the value of the CPU timer in microseconds in location TIMELEFT. 

CPUTIMER MIC, TIMELEFT 



Store the value of the CPU timer in time units in the location addressed by register 

CPUTIMER TU, (1) 



Operation 
1. 



Operation: Store the value of the CPU timer in timer units in location TIMELEFT. If an 
error occurs, transfer control to the error routine labeled ERREXIT. 

CPUTIMER , TIMELEFT, ERRET=ERREXIT 



Operation: Place the value of the CPU timer in microseconds in the location addressed by 
register 1 . If an error occurs, transfer control to the address in register 2. 

CPUTIMER MIC , ( 1 ) , ERRET= ( 2 ) 
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DELETE — Relinquish Control of a Load Module 



The DELETE macro instruction cancels the effect of a previous LOAD macro instruction. If 
DELETE cancels the only outstanding LOAD request for the module and no other 
requirements exist for the module, the virtual storage occupied by the load module is released 
and is available for reassignment by the control program. 

The entry name specified in the DELETE macro instruction must be the same as that specified 
in the LOAD macro instruction that brought the load module into storage. Also, the DELETE 
macro instruction must be issued by the same task that issued the LOAD macro instruction. 

Any module loaded by a task will not be removed from virtual storage until the DELETE 
macro instruction is issued or end of task is reached. In addition, any module loaded by a 
system task will not be removed from virtual storage until a DELETE macro instruction is 
issued by a system task or end of task is reached. 

The DELETE macro instruction is written as follows: 



name 


name: symbol. Begin name in column 1. 


h 


One or more blanks must precede DELETE. 


DELETE 




b 


One or more blanks must follow DELETE. 


EP = entry name 

EPLOC = entry name addr 

'DE = list entry addr 


entry name: symbol. 

entry name addr: RX-type address, or register (0) or (2) - (12). 
list entry addr: RX-type address, or register (0) or (2) - (12). 


,RELATED = va/Me 


value: any valid macro keyword specification. 



The parameters are explained as follows: 

EP = entry name 
EPLOC = entry name addr 
DE'^ list entry addr 

specifies the entry name, the address of the entry name, or the address of a 60-byte list 
entry for the entry name that was constructed using the BLDL macro instruction. If 
EPLOC is coded, the name must be padded to eight bytes, if necessary. 

,RELATED = va/Me 

specifies information used to self-document macro instructions by 'relating' functions or 
services to corresponding functions or services. The format and contents of the 
information specified are at the discretion of the user, and may be any vaUd coding 
values. 

The RELATED parameter is available on macro instructions that provide opposite 
services (for example, ATTACH/DETACH, GETMAIN/FREEMAIN, and 
LOAD/DELETE), and on macro instructions that relate to previous occurrences of the 
same macro instructions (for example, CHAP and ESTAE), 
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The RELATED parameter may be used, for example, as follows: 

LOADl LOAD EP=APGI0HK1 ,RELATED= ( DELI , 

• LOAD APGIOHKl ' ) 

DELI DELETE EP=APGI0HK1 ,RELATED= (LOADl , 

• DELETE APGIOHKl ' ) 

Note: Each of these macro instructions will fit on one line when coded, so there is no 
need for a continuation indicator. 

When control is returned, register 15 contains one of the following return codes: 

Hexadecimal 

Code Meaniog 

00 Successful completion of requested function. 

04 Request was not issued for this module, or attempt was made to delete a system module. 

Example 1 

Operation: Remove a module (PGMTOVLY) from virtual storage. 
DELETE EP=PGMTOVLY 
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DEQ — ■ Release a Serially Reusable Resource 



The DEQ macro instruction removes control of one or more serially reusable resources from 
the active task. Register 15 is set to 0 if the request is satisfied. An unconditional request to 
release a resource from a task that is not in control of the resource, or a request that contains 
invalid parameters results in abnormal termination of the task. 

Note: When global resource serialization is active, the SYSTEM inclusion resource name list 
and the SYSTEMS exclusion resource name list are searched for every resource specified with a 
scope of SYSTEM or SYSTEMS. A resource whose name appears in one of these resource 
name lists might have its scope changed from the scope that appears on the macro instruction. 
See Planning: Global Resource Serialization for more information. 

The standard form of the DEQ macro instruction is written as follows: 



ncme name: symbol. Begin name in column 1. 

b One or more blanks must precede DEQ. 
DEQ 

b One or more blanks must follow DEQ. 



qname addr: A-type address, or register (2) - (12). 

rname addr: A-type address, or register (2) - 12). 

mame length: symbol, decimal digit, or register (2) - (12). 
Note: mcane length must be coded if a register is specified for rname addr. 

[step Default: STEP 

.SYSTEM 

.SYSTEMS 

) 

,RET = HAVE Default: RET = NONE 

,RET = NONE 

,RELATED = va/iie value: any valid macro keyword specification. 



( 

qname addr 
,rname addr 

9 

,rrumie length 



The parameters are explained as follows: 

( 

specifies the beginning of the resource(s) description, 
qname addr 

specifies the address in virtual storage of an 8 -character name. The name can contain any 
valid hexadecimal digits. The qname must be the same name specified for the resource in 
an ENQ macro instruction. 

^rname addr 

specifies the address in virtual storage of the name used in conjunction with qname and 
scope to represent the resource acquired by a previous ENQ macro instruction. The name 
can be qualified, must be from 1 to 255 bytes long, and can contain any valid 
hexadecimal digits. The mame must be the same name specified for the resource in an 
ENQ macro instruction. 
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,rname length 

specifies the length of the mame described above. The length must have the same value 
as specified in the previous ENQ macro instruction. If this parameter is omitted, the 
assembled length of the mame is used. You can specify a value between 1 and 255 to 
override the assembled length, or you may specify a value of 0. If 0 is specified, the 
length of the mame must be contained in the first byte at the mame addr specified above. 

IsTEP 

,SYSTEM 

,SYSTEMS 

specifies the scope of the resource. You must specify the same STEP, SYSTEM, or 
SYSTEMS option as you used in the ENQ macro instruction requesting the resource. 

) 

specifies the end of the resource(s) description. 

Note: The parameters qname addr, mame addr, mame length, and the scope can be 
repeated within a single set of parentheses to indicate multiple resources. These 
parameters can be repeated until there is a maximum of 255 characters including the 
parentheses. 

,RET=HAVE 
,RET = NONE 

specifies that the request for releasing the resources named in DEQ is to be conditional 
(HAVE) or unconditional (NONE). If this parameter is omitted, the request for release is 
unconditional, and the active task is abnormally terminated if it has not been assigned 
control of the resources. 

HAVE specifies that the request to release the resources named in the DEQ macro 
instruction is to be honored only if the active task has been assigned control of the 
resources. A return code is set if the resource is not held. 

NONE specifies an unconditional request to release the resources. The active task is 
abnormally terminated if it has not been assigned control of the resources. If the 
parameter is omitted, NONE is the default. 

,RELATED = va/Me 

specifies information used to self-document macro instructions by 'relating' functions or 
services to corresponding functions or services. The format and contents of the 
information specified are at the discretion of the user, and can be any valid coding values. 

. The RELATED parameter is available on macro instructions that provide opposite 
services (for example, ATTACH/DETACH, GETMAIN/FREEMAIN, and 
LOAD/DELETE), and on macro instructions that relate to previous occurrences of the 
same macro instructions (for example, CHAP and ESTAE). 
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The RELATED parameter may be used, for example, as follows: 



ENQUEUE ENQ 



( MAJOR, MINOR, S, 8, STEP) , 

RELATED= ( DEQUEUE , ' OBTAIN RESOURCE ' ) 



X 



DEQUEUE DEQ 



(MAJOR, MINOR, 8, STEP) , 

RELATED= (ENQUEUE , ' RELEASE RESOURCE ' ) 



Return codes are provided by the control program only if RET = HAVE is designated. If 
all of the return codes for the resources named in DEQ are 0, register 15 contains 0. If 
any of the return codes are not 0, register 15 contains the address of a virtual storage area 
containing the return codes as shown in Figure 50. The return codes are placed in the 
parameter list resulting from the macro expansion in the same sequence as the resource 
names in the DEQ macro instruction. The return codes are shown in Figure 51. 



Address 
Returned in 
Register 15 



Return 
Codes 



12 



24 



36 



12 



RC 1 



RC 2 



RC 3 



Return codes ore 
12 bytes apart, 
storting 3 bytes 
from the address 
in register 15. 



RC N 



Figure 50. Return Code Area Used by DEQ 
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Hexadecunal 

Code Meaning 



0 The resource has been released. 

4 The resource has been requested for the task, but the task has not been assigned control. The task is 

not removed from the wait condition. (This return code could result if DEQ is issued within an exit 
routine which was given control because of an interruption.) 

8 Control of the resource has not been requested by the active task, or the resource has already been 

released. 



Figure 51. DEQ Macro Instruction Return Codes 



Example 1 

Operation: Release control of the resource in Example 1 of ENQ, (later in this section) if it has 
been assigned to the current task. The length of the mame is explicitly defined as 9 characters. 

DEQ ( MAJOR 1 , MINOR 1 , 9 , STEP ) , RET=HAVE 

Example 2 

Operation: Unconditionally release control of the resources in Example 2 of ENQ. The length 
of the mame for the first resource is 3 characters and the length of the mame for the third 
resource is 8 characters. Allow the length of the second resource to default to its assembled 
length. 

DEQ { MA JOR4 , MIN0R4 , 3 , STEP , MA J0R2 , MIN0R2 , , SYSTEM , X 
MAJORS , MINORS , 8 , SYSTEMS ) 
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DEQ (List Fomi) 



Use the list form of the DEQ macro instruction to construct a DEQ parameter list. The 
number of qname, mame, and scope combinations in the list form of DEQ must be equal to the 
maximum number of qname, mame and scope combinations in any execute form of DEQ that 
refers to that hst form. 



The list form of the DEQ macro instruction is written as follows: 



name 


name: symbol. Begin ntane in column I. 


b 


One or more blanks must precede DEQ. 


DEQ 




u 


One or more blanks must follow DEQ. 


( 

qname addr 


qname addr: A-type address. 


,mame addr 


rname addr: A-type address. 


,rname length 


rruime length: symbol or decimal digit. 


!sTEP 

.SYSTEM 

.SYSTEMS 


Default: STEP 


) 

.RET = HAVE 
.RET = NONE 




.RELATED = va/Me 


value: any valid macro keyword specification. 


,MF = L 





The parameters are explained under the standard form of the DEQ macro instruction, with the 
following exception: 

,MF = L 

specifies the list form of the DEQ macro instruction. 
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DEQ (Execute Form) 



A remote control program parameter list is used in, and can be modified by, the execute form 
of the DEQ macro. The parameter list can be generated by the list form of either the DEQ or 
the ENQ macro instruction. al.The execute form of the DEQ macro instruction is written as 
follows: 



name name: symbol. Begin name in column 1. 

b One or more blanks must precede DEQ. 
DEQ 

b One or more blanks must follow DEQ. 



qname addr 
,rname addr 

,rname length 



Note: ( and ) are the beginning and end of a parameter list. The entire hst is 
optional. If nothing in the list is desired, the (, ), and all parameters between ( 
and ) should not be specified. If something in the Ust is desired, the (, ), and all 
parameters in the list should be specified as indicated at the left. 

qname addr: RX-type address, or register (2) - (12). 

rname addr: RX-type address, or register (2) - (12). 

rname length: symbol, decimal digit or register (2) - (12). 



,STEP Default: STEP 

.SYSTEM 

,SYSTEMS 

) Note: See note opposite ( above. 

,RET = HAVE Default: RET = NONE 

,RET = NONE 

,RELATED = value value: any valid macro keyword specification. 

MP = i^,ctrl addr) ctrl addr: RX-type address, or register (1) - (12). 



The parameters are explained under the standard form of the DEQ macro instruction, with the 
following exception: 

,ME = (E,ctrl addr) 

specifies the execute form of the DEQ macro instruction using a DEQ parameter list. 
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DETACH — Detach a Subtask 



The DETACH macro instruction is used to remove from the system a subtask created by an 
ATTACH macro instruction that specified the ECB or ETXR parameter. Each subtask created 
in this manner must be removed from the system before the originating task terminates. 
Failure to remove these subtasks causes abnormal termination of the originating task and all of 
its subtasks. Issuing a DETACH macro instruction that specifies a subtask created without the 
ECB or ETXR parameter also causes abnormal termination of the originating task when the 
specified subtask has already terminated. Issuing a DETACH macro instruction that specifies a 
subtask that has not terminated causes termination of that subtask and all of its subtasks. A 
DETACH macro instruction can be issued only for subtasks created by the active task. 

The DETACH macro instruction is written as follows: 



name 


name: symbol. Begin name in column 1. 


b 


One or more blanks must precede DETACH. 


DETACH 




b 


One or more blanks must follow DETACH. 


tcb addr 


tcb addr: symbol, RX-type address, or register (1) or (2) - (12). 


,STAE=NO 


Default: STAE=NO 


,STAE = YES 




,RELATED = v<i/ue 


value: any valid macro keyword specification. 



The parameters are explained as follows: 
tcb addr 

specifies the address of a fullword on a fuUword boundary containing the address of the 
task control block for the subtask to be removed from the system. 

Note: tcb addr specifies a storage location below 16 Mb. 

,STAE = NO 
,STAE = YES 

specifies whether the exit routine specified in a STAE macro instruction issued by the 
subtask, or STAI/ESTAE/ESTAI exits existing for the subtasks, is or is not to be given 
control if the subtask is detached before it has been terminated. If a retry routine is 
specified by the STAE exit routine, it is not given control. 

,R£LAT£D = va/ue 

specifies information used to self-document macro instructions by 'relating' functions or 
services to corresponding functions or services. The format and contents of the 
information specified are at the discretion of the user, and may be any valid coding 
values. 

The RELATED parameter is available on macro instructions that provide opposite 
services (for example, ATTACH/DETACH, GETMAIN/FREEMAIN, and 
LOAD/DELETE), and on macro instructions that relate to previous occurrences of the 
same macro instructions (for example, CHAP and ESTAE). 
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The RELATED parameter may be used, for example, as follows: 



ATTCHl ATTACH EP=MYJOB ,ECB=MYECB ,RELATED= (DETCHl , 
• CREATE SUBTASK ' ) 
ST 1,TCBADDR SAVE TCB ADDRESS 

WAIT 1,MYECB WAIT FOR SUBTASK 

TO COMPLETE 

DETCHl DETACH TCBADDR , RELATED= ( ATTCHl , ' DETACH SUBTASK ' ) 

Note: The ATTACH macro instruction will fit on one line when coded, so there is no 
need for a continuation indicator. 

When control is returned, register 15 contains one of the following return codes: 

Hexadecimal 

Code Meanii^ 

00 Successful completion. 

04 An incomplete subtask was detached with STAE=YES specified; DETACH processing successfully 

completed. 

Example 1 

Operation: Cause the subtask to be removed from the address space. The address of the TCB 
is in the fuUword labeled SAVEWORD. 

DETACH SAVEWORD 

Example 2 

Operation: In addition to causing the subtask to be removed from the address space, give 
control to the most recent STAE exit estabUshed by the subtask if the subtask has not yet been 
terminated. 

DETACH (1),STAE=YES 
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DIV 



— Data-in- Virtual 



The DIV macro lets you access a data object on permanent storage via paging I/O and process 
this object through normal virtual storage addressing. Data-in-virtual maps the object onto a 
single virtual address range so your program can view it as beginning at a virtual location and 
occupying a consecutive virtual address range. The DIV macro performs the following eight 
services: 

• IDENTIFY 

• ACCESS 

• MAP 

• RESET 

• SAVE 

• UNMAP 

• UNACCESS 

• UNIDENTIFY 

The standard form of the DIV macro instruction is written as follows: 



name name: symbol. Begin name in column 1. 

b One or more blanks must precede DIV. 
DIV 

b One or more blanks must follow DIV. 



Valid parameters: 

IDENTIFY ID, TYPE, DDNAME 

ACCESS ID, MODE, SIZE 

MAP ID, AREA, OFFSET, SPAN, RETAIN 

RESET ID, OFFSET, SPAN 

SAVE ID, OFFSET, SPAN, SIZE 

UNMAP ID, AREA, RETAIN 

UNACCESS ID 

UNIDENTIFY ID 

,1D = addr 

,AREA= addr addr: Rx type address or register (2) - (12) 



,DDT^AME= addr 

,MODE = READ 
,MODE = UPDATE 

,OFFSET=addr 
.OFFSET = * 

.RETAIN = YES 
.RETAIN = NO 

,SIZE = addr 
,SIZE = * 

,SPAN = addr 
,SPAN = * 
,TYPE = DA 



Default: OFFSET =0 

Default: RETAIN = NO 

See explanation of parameters if omitted 

See explanation of parameters if omitted 
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The IDENTIFY, ACCESS, MAP, SAVE, RESET, UNMAP, UNACCESS and UNIDENTIFY 
parameters, which designate the services of the DIV macro, are mutually exclusive. You can 
select only one. The parameters are explained as follows: 

roENTIFY 

selects the data-in- virtual object (linear data set) that you want to process. When you 
specify IDENTIFY, you must also specify ID, DDNAME and TYPE. ID specifies the 
address of an eight-byte field, DDNAME specifies the object, and TYPE specifies the 
storage format of the DDNAME. The IDENTIFY service creates a unique eight-byte 
internal name that is returned at the address specified by the ID parameter. This name is 
a token that represents the use of the selected object within your task. When you invoke 
other data-in-virtual services, you use this token as the ID input parameter. 

ACCESS 

requests permission to access a data-in-virtual object. When you specify ACCESS, you 
must also specify ID and MODE and you may optionally specify SIZE. The ID 
parameter, which provides the address of the unique name that was returned by the 
IDENTIFY service, indicates the object you want to access. If SIZE is specified, the 
macro returns ttie current size of the object in the location that SIZE designates. If 
specified, MODE indicates whether the object will be accessed for reading or updating. 

MAP 

specifies a request to establish addressability to the object in a specified range of virtual 
storage, called the virtual window. When you specify MAP, you must also specify ID and 
AREA, and you may optionally specify OFFSET, SPAN, and RETAIN. The ID 
parameter, which provides the address of the unique name that was returned by the 
IDENTIFY service, selects the object that you 'want to map. AREA indicates the starting 
address of the virtual window. OFFSET and SPAN specify the range of blocks on the 
object that is to be mapped to the window. RETAIN indicates whether or not data 
previously existing in the virtual window is kept, or replaced by data from the object data. 

RESET 

releases changes made in the window since the last SAVE operation. When you specify 
RESET, you must also specify ID, and you may optionally specify OFFSET and SPAN. 
ID, which provides the address of the unique name that was returned by the IDENTIFY 
service, indicates the virtual window that you want to reset. OFFSET and SPAN specify 
the range of blocks on the object that corresponds to the virtual window. Data in pages of 
mapped virtual windows that correspond to the RESET range will be replaced. If the 
window corresponds to blocks on the object, the data is replaced by the current contents 
of the object. If the window corresponds to blocks offset beyond the end of the object, the 
data is not relevant (as if the pages had just been obtained by a GETMAIN). No change 
to the object itself will be made by a RESET. 

SAVE 

specifies that data from the window is to be saved. Saving is accomplished by writing 
changed pages from the window to the corresponding blocks of the object. When you 
specify SAVE, you must also specify ID, and you may optionally specify OFFSET, SPAN 
and SIZE. ID, which specifies the unique name that was returned by the IDENTIFY 
service, selects the object into which the blocks are written. OFFSET and SPAN specify 
the data blocks, relative to the beginning of the object, that are to be saved. Changed 
pages from the window are then written into those blocks. 
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UNMAP 

specifies a request to terminate a virtual window by removing the correspondence between 
virtual pages in the window and blocks on the object. After the UNMAP is complete, the 
contents of the pages depend on the value you specify for RETAIN; the virtual pages in 
the former window either retain a copy of the data that was on the corresponding blocks 
of the object, or appear as if they had just been obtained by a GETMAIN. 

When you specify UNMAP, you must also specify ID and AREA, and you may specify 
RETAIN. ID provides the address of the unique name that was returned by the 
IDENTIFY service, the same name that was input to the MAP service that created the 
window. AREA specifies the starting address of the virtual window. RETAIN specifies 
whether data from the object is to be retained or discarded. If you specify 
RETAIN = YES, the data from the object is retained in virtual storage. If you specify 
RETAIN = NO, the data is discarded from virtual storage, leaving the appearance of data 
that has been just obtained by a GETMAIN. RETAIN = NO is the default. UNMAP has 
no effect on the object itself and does not save data from the virtual window. If you want 
to save the data in the window, then invoke the SAVE before you invoke UNMAP. 

UNACCESS 

specifies that you are relinquishing your permission to read from or write to a 
data-in-virtual object. When you specify UNACCESS, you must also specify ID, which 
provides the address of the unique name that was returned by the IDENTIFY service. 
When UNACCESS is invoked, any outstanding windows for the specified ID are 
automatically unmapped with an implied RETAIN = NO. 

UNIDENTIFY 

specifies that the use of a data-in-virtual object under a previously assigned ID is ended. 
When you specify UNIDENTIFY, you must also specify ID, which provides the address 
of the unique name that was returned by the IDENTIFY service. If the object is still 
accessed or mapped under the specified ID, the system will automatically unaccess and 
unmap it with an implied RETAIN = NO. 

,ro =addr 

specifies the address of a field in storage where the IDENTIFY service stores a unique 
eight-byte name that it associates with the object. This name, which is like a token, is the 
output value of the IDENTIFY service; it is a required input value for all the other 
services. 

,AREA address 

specifies the address of a four-byte field in storage containing a pointer to the start of the 
virtual window. The AREA parameter must be specified when you invoke the MAP and 
the UNMAP services. The starting address for an UNMAP request must be identical to 
the starting address of its corresponding MAP request. The virtual storage area that is 
occupied by a window must meet the following requirements: 

• The window must begin on a 4096-byte (page) boundary and must be a multiple of 
4096 bytes long. 

• Virtual storage within the window must have been obtained by the GETMAIN macro 
from a single, pageable, private area subpool owned by the task that issued the 
IDENTIFY. 

• The window cannot contain VIO storage. 

• Pages within the window cannot be page fixed. 
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DDNAME =addr 

specifies the address of a field containing the ddname for the object. The first byte of the 
field must be the number of characters in the ddname. The bytes following the first byte 
must contain the EBCDIC characters of the ddname itself. The ddname must conform to 
the standard sjmitax for ddnames. (One through eight alphameric or national characters, 
the first of which must be alphabetic or national.) DDNAME is required when you 
invoke IDENTIFY but it is not allowed when you invoke other services of the DIV 
macro. 

,MODE = READ 
,MODE = UPDATE 

specifies whether the object is being accessed for the purpose of reading or updating. If 
you are using the SAVE service to update an object, specify MODE = UPDATE. 
Otherwise, specify MODE =^ READ to signify read-only access to the object. MODE must 
be specified whenever you specify ACCESS. 

,OFFSET =addr 
,OFFSET = * 

specifies the beginning of a continuous string of blocks in a data-in-virtual object. 
OFFSET is used with SPAN to define a continuous string of blocks in an object. 
OFFSET designates the location of the first block in the string, and SPAN designates 
how many blocks are in the string. An OFFSET value of zero designates the first block 
(the beginning) of an object. An OFFSET beyond the current end of the object is 
permitted as long as it remains within the maximum number of blocks allowed for the 
object and also within the absolute limit of (2**20)-l. if you omit offset or specify 
offset = *, a default OFFSET of zero is used. The OFFSET parameter can be specified 
with the MAP, RESET, and SAVE services. 

,RETAIN=YES 
,RETAIN = NO 

specifies the retain mode of the window, which controls the actions of the MAP, 
UNMAP, and SAVE services. The retain mode determines what data appears in the 
window when the MAP service is invoked, and what data is left in virtual storage when 
UNMAP is invoked. It also affects how blocks are saved when you invoke the SAVE 
service, and how blocks are reset when you invoke RESET. The RETAIN parameter may 
be specified when you specify the MAP and the UNMAP parameters of the DIV macro. 
If the RETAIN parameter is not specified, the retain mode defaults to NO. 

,SIZE ^addr 
,SIZE = * 

specifies the address of a four-byte field where the system stores the size of the object. The 
size is stored in this field as a return value whenever you specify SAVE or ACCESS and 
also specify SIZE. When control is returned after the execution of a SAVE, the value that 
is returned is the minimum number of blocks that must be mapped to ensure that the 
entire object is mapped. If you omit SIZE or specify SIZE = *, then the size is not 
returned. 

The size parameter may only be specified when you specify MAP, RESET, or SAVE. 
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,SPAN =addr 
,SPAN = * 

specifies the address of a four-byte field containing the number of blocks that are to be 
processed by the MAP, RESET, or SAVE services. These services operate only on a string 
of contiguous blocks. SPAN indicates how many blocks are in the string. It is used with 
OFFSET, which indicates the first block of the string. 

For the RESET and SAVE services, the block string can include discontiguous mappings 
of an object. This lets you reset or save several maps in a single DIV macro invocation. 

For the MAP service, the block string can extend beyond the end of the object, but it 
cannot extend beyond the maximum size allowed for the object. You can create a window 
that exceeds the size of the object. The maximum span allowed is (2**20)-l bytes. 

If you omit SPAN or specify SPAN = *, the SPAN default value is used. The default is 
also be used if the four-byte field contains zero. For the SAVE and RESET services, the 
default value is the number of blocks in the object from the specified or defaulted block 
to the end of the last mapped range. For the MAP service, the default is the current size 
of the object in blocks, minus the value specified by OFFSET. If the offset value is 
beyond the end of the object, the span defaults to one when you omit SPAN. 

SPAN may be specified only when you specify MAP, RESET or SAVE. 

,TYPE = DA 

specifies that your program is using a data definition statement to identify the object. You 
must specify TYPE = DA whenever you specify IDENTIFY. 
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DIV (List Form) 



The list form of the DIV macro instruction is written as follows: 



name 


nonte: symbol. Begin nome in column 1. 


b 


One or more blanks must precede DIV. 


DIV 




b 


One or more blanks must follow DIV. 




Valid parametcfs: 


IDENTIFY 


ID, TYPE, DDNAME 


ACCESS 


ID, MODE, SIZE 


MAP 


ID, AREA, OFFSET, SPAN, RETAIN 


IS.Cn3Ci I 




SAVE 


ID, OFFSET, SPAN, SIZE 


UNMAP. 


ID, AREA, RETAIN 


UNACCESS 


ID 


UNIDENTIFY 


ID 


,AREA = arfrfr 


Initialized to zero if omitted 




addr: A-type address 


,DDNAME = a</<*- 


Initialized to zero if omitted 


,lT> = addr 


Initialized to zero if omitted 


,MODE = READ 


Initialized to zero if omitted 


,MODE = UPDATE 




,TYPE = DA 


Initialized to zero if omitted 


,0¥¥SET: = addr 


Default: OFFSET=0. 


,OFFSET = * 




.RETAIN = YES 


Default: RETAIN = NO 


.RETAIN = NO 




,SlZE = addr 


See explanation of parameters if omitted 


,SIZE = * 




,SPAN=flrfrfrSee explanation of parameters if omitted 


,SPAN = * 




,MF = L 





,MF = L 

specifies the list form of the DIV macro. The Ust form generates the DIV parameter Ust 
in Hne without any executable code or register usage. 
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DIV (Execute Form) 



The execute form of the DIV macro instruction is written as follows: 



name 


name: symbol. Begin name in column 1 . 


b 


One or more blanks must precede DIV. 


DIV 




b 


One or more blanks must follow DIV. 




Valid parameters: 


IDENTIFY 


ID, TYPE, DDNAME 


ACCESS 


ID, MODE, SIZE 


MAP 


ID, AREA, OFFSET, SPAN, RETAIN 


RESET 


ID, OFFSET, SPAN 


SAVE 


ID, OFFSET, SPAN, SIZE 


UNMAP 


ID, AREA, RETAIN 


UNACCESS 


ID 


UNIDENTIFY 


ID 


aupa — /i/Wr 
,/\K.CJ\ — uaur 


No change in executable parameter list if omitted 




addr: Rx type address or register (2) - (12) 


,iJUirit\ald — auur 


No change in executable parameter list if omitted 


,ID = addr 


No change in executable parameter list if omitted 


,MODE = READ 


No change in executable parameter list if omitted 


,MODE = UPDATE 




,TYPE = DA 


No change in executable parameter list if omitted 


,OFFSET = addr 


Default: OFFSET =0 


.OFFSET = * 




.RETAIN = YES 


Default: RETAIN = NO 


.RETAIN = NO 




,S1ZE = addr 


See explanation of parameters if omitted 


,SIZE = * 




,SPAN = addr 


See explanation of parameters if omitted 


,SPAN = * 




M¥=iE,addr) 





,MF = (E,addr) 

specifies the Execute form. In the Execute form, DIV will be called using the parameter 
list specified by "addr." "addr" indicates the address of the parameter list and may be (a) 
any address that is valid in an RX-type assembler language instruction or (b) one of the 
general registers 2 through 12 specified within parentheses. The register may be expressed 
either symbolically or as a decimal number. The specified parameter list will be updated 
for any parameters that are specified. Other parameter fields will be unaffected. 
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DIV (Modify Form) 



The modify form of the DIV macro instruction is written as follows: 



b 

DIV 
b 



One or more blanks must precede DIV. 



One or more blanks must follow DIV. 



IDENTIFY 

ACCESS 

MAP 

RESET 

SAVE 

UNMAP 

UNACCESS 

UNIDEISTTIFY 

,AREA = c</</r 

,DDNAME = flrfrfr 

,ID = addr 

.MODE = READ 
,MODE = UPDATE 

,TYPE = DA 

.OFFSET = arfrf/- 
.OFFSET = * 

.RETAIN = YES 
.RETAIN -NO 

,SIZE = addr 
,SIZE = * 

,SFAN = addr 
,SPAN = * 

,MF = (M,addr) 



Valid parameters: 

ID, TYPE. DDNAME 
ID. MODE. SIZE 

ID, AREA. OFFSET, SPAN, RETAIN 

ID, OFFSET. SPAN 

ID. OFFSET. SPAN. SIZE 

ID, AREA, RETAIN 

ID 

ID 

No change in executable parameter list if omitted 
addr: Rx type address or register (2) - (12) 

No change in executable parameter list if omitted 

No change in executable parameter list if omitted 

No change in executable parameter list if omitted 

No change in executable parameter list if omitted 
Default: OFFSET = 0 

Default: RETAIN = NO 

See explanation of parameters if omitted 

See explanation of parameters if omitted 

See explanation of parameters if omitted. 



,MF = iM,addr) 

specifies the MODIFY form. The modify form of the macro is used to modify an already 
defined DIV parameter list. It is exactly the same as the EXECUTE form except that 
DIV is not called. Registers 1 and 15 are destroyed. 
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DOM — Delete Operator Message 



The DOM macro instruction is used to delete an operator message or group of messages from 
the display screen of the operator's console. It can also prevent messages from ever appearing 
on any operator's console. When a program no longer requires that a message be displayed, it 
can issue the DOM macro instruction to delete the message. 

Depending on the timing of the DOM relative to the WTO(R), the message may or may not be 
displayed. If the message is being displayed, it is removed when space is required for other 
messages. 

When a WTO or WTOR macro instruction is issued, the system assigns an identification 
number to the message and returns this number (24 bits right-justified) to the issuing program 
in general register 1. When the display of this message is no longer needed, you can issue the 
DOM macro instruction using the identification number that was returned in general register 1. 

The DOM macro instruction is written as follows: 



name 


name: symbol. Begin name in column 1. 


b 


One or more blanks must precede DOM. 


DOM 




b 


One or more blanks must follow DOM. 


MSG = addr 


addr: register (1) - (12), or an address. 


MSGUST = list addr 


list addr: symbol, RX-type address, or register (1) - (12). 


TOKEN =addr 


addr: register (1) - (12), or an address. 


,COUNT = arfrfr 


addr: register (2) - (12), or an address. 


,REPLY=YES 





The parameters are explained as follows: 

MSG = 
MSGLIST = 

specifies the message numbers of messages to be deleted. 

For MSG, the address or register contains the 24-bit, right-justified 
identification number of the message to be deleted. Use this parameter to delete a 
single message. If you use register 1, the macro expansion is shortened by two bytes. 

For MSGLIST, the address is of a list of one or more fullwords, each word containing a 
24-bit, right-justified identification number of a message to be deleted. A maximum of 60 
identification numbers may be in the message list. If more than 60 identification numbers 
are in the list, only the first 60 are processed. Begin the Ust on a fullword boundary. 
When you are not using the COUNT parameter, indicate the end of the list by setting the 
high-order bit of the last fullword entry to 1. If you use register 1, the macro expansion is 
shortened by four bytes. If any register from 2 through 12 is used, the macro expansion is 
shortened by two bytes. 
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,COUNT = 

The count field or register contains the one-byte count of 4-byte DOM ids associated with 
this request. The count value must be from 1 to 60. If this keyword is used, the issuer 
must not set the high order bit on in the last entry of the DOM parameter list. If this 
keyword is not specified, the DOM ids are treated as 3-byte ids. If an address is used 
instead of a register, the address points to a 1-byte field which contains the count. The 
COUNT keyword is invahd with the TOKEN keyword. 

,REPLY = YES 

specifies that the need for a reply to a WTOR message has been eliminated. 
REPLY = YES is invaUd with TOKEN and COUNT. When you specify REPLY = YES, 
you must specify either MSG or MSGLIST to identify the message or group of messages 
that is to be deleted. 

TOKEN = 

The field or register contains the 4-byte TOKEN of the messages that are to be deleted. 
The messages that are deleted by TOKEN are the messages that were issued with this 
TOKEN via WTO. Unauthorized users may delete only those messages which were 
originally issued under the same jobstep TCB, ASID and system id. No DOM ids can be 
specified with this keyword. This keyword is mutually exclusive with the MSG, 
MSGLIST, and COUNT keywords. 

Note: For any DOM keywords that allow a register specification, the value must be 
right-justified in the register and the remaining bytes within the register must be zero. 

Example 1 

Operation: Delete an operator message whose message id is in register 1. 
DOM MSG=(1) 

Example 2 

Operation: Delete a list of operator messages, some of which may be WTORs. 

DOM MSGLIST=ID2,REPLY=YES 

Example 3 

Operation: Delete a number of operator messages. The COUNT parameter indicates how 
many messages are to be deleted. 

DOM MSGLIST=ID3,COUNT=COUNT4 

Example 4 

Operation: Delete all messages issued with a particular token. 
DOM T0KEN=T0KEN1 
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ENQ 



— Request Control of a Serially Reusable Resource 



ENQ requests the control program to assign control of one or more serially reusable resources 
to the active task. If any of the resources are not available, the active task might be placed in a 
wait condition until all of the requested resources are available. Once control of a resource has 
been assigned to a tas]c, it remains with that task until a DEQ macro instruction is issued or the 
task terminates. Register 15 is set to 0 if the request is satisfied. 

You can also use ENQ to determine the status of the resource; whether it is immediately 
available or in use, and whether control has been previously requested for the active task in 
another ENQ macro instruction. 

You can request either shared or exclusive use of a resource. The resource is represented in the 
ENQ by a pair of names, the qname and the mame, and a scope value. In order for ENQ/DEQ 
to coordinate the use of the resources: 

• Everyone must use ENQ/DEQ. 

• Everyone must use the same names and scope values for the same resources. 

• Everyone must use consistent ENQ/DEQ protocol. . 

Issuing two ENQ macro instructions for one task for the same resource without an intervening 
DEQ macro instruction results in abnormal termination of the task, unless the second ENQ 
designates RET = TEST, USE, CHNG, or HAVE. If a task terminates while it still has control 
of any resources, all requests that this task made are automatically dequeued. 

Global resource serialization counts and limits the number of concurrent resource requests from 
an address space. If an unconditional ENQ (an ENQ that uses the RET = NONE option) 
causes the count of concurrent resource requests to exceed the limit, the caller is abended with a 
system code of X'538'. See "Limiting Concurrent Requests for Resources" in Part I. 

Note: When global resource seriaUzation is active, the SYSTEM inclusion resource name list 
and the SYSTEMS exclusion resource name list are searched for every resource specified with a 
scope of SYSTEM or SYSTEMS. A resource whose name appears in one of these resource 
name lists might have its scope changed from the scope that appears on the macro instruction. 
See Planning: Global Resource Serialization for more information. 



ENQ — Request Control of a Serially Reusable Resource 1 73 



The standard form of the ENQ macro instruction is written as follows: 



b 

ENQ 
b 



name: symbol. Begin name in column 1. 
One or more blanks must precede ENQ. 

One or more blanks must follow ENQ. 



( 

qname addr 
,rname addr 

j-name length 



,STEP 

,SYSTEM 

.SYSTEMS 

) 



,RET = CHNG 

,RET=HAVE 

,RET=TEST 

,RET=USE 

,RET=NONE 



qname addr: A-type address, or register (2) - (12). 
rname addr: A-type address, or register (2) - (12). 
Default: E 

rname length: symbol, decimal digit, or register (2) - (12). 
Default: assembled length of rruane 

Default: STEP 



Default: RET = NONE 



.RELATED = va/«e 



value: any valid macro keyword specification. 



The parameters are explained as follows: 
( 

specifies the beginning of the resource(s) description. 



qname addr 

specifies the address in virtual storage of an 8-character name. The name can contain any 
valid hexadecimal character. Every program issuing a request for a serially reusable 
resource must use the same qname, rname, and scope to represent the resource. (See the 
section "Naming the Resource" for restrictions on naming qname.) 

ymame addr 

specifies the address in virtual storage of the name used in conjunction with qname to 
represent a single resource. The name must be from 1 to 255 bytes long and can contain 
any vaUd hexadecimal characters. The rname length must be specified if either the name 
specified in the rname field, or the length attribute on the rname is defined by an EQU 
assembler instruction. Additionally, the rname length must be coded if tiie rname addr 
field is coded as a register. 



,E 

specifies whether the request is for exclusive (E) or shared (S) control of the resource. If 
the resource is modified while under control of the task, the request must be for exclusive 
control; if the resource is not modified, the request should be for shared control. 
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,mame length 

specifies the length of the mame described above. If this parameter is omitted, the 
assembled length of the mame is used. You can specify a value between 1 and 255 to 
override the assembled length, or you may specify a value of 0. If 0 is specified, the 
length of the mame must be contained in the first byte at the mame addr specified above. 
This mame length parameter may be specified as an expUcit constant (decimal digit), a 
label from an EQU assembler instruction (symbol), or a register (2)-(12). The mame 
length must be specified if either the name specified in the mame field, or the length 
attribute of the mame is defined by an EQU assembler instruction. Additionally, the 
mame length must be coded if the mame addr field is coded as a register. 

isTEP 

,SYSTEM 

.SYSTEMS 

specifies the scope of the resource used only within an address space (STEP), used by 
programs of more than one address space (SYSTEM), or shared between systems 
(SYSTEMS). If STEP is specified, a request for the same qname and mame from a 
program in another address space denotes a different resource. If SYSTEM or 
SYSTEMS is specified, requests for the same qname, mame, and scope from programs of 
any address space denote the same resource. 

STEP, SYSTEM, and SYSTEMS are mutually exclusive and do not refer to the same 
resource. If two macro instructions specify the same qname and mame, but one specifies 
STEP and the other specifies SYSTEM or SYSTEMS, they are treated as requests for 
different resources. 

Note: The SYSTEM option is not the same as the SYSTEMS option. When you specify 
SYSTEMS, you are spreading the scope of the resource across two or more processors. 
SYSTEM confines the scope to a single processor, but it includes two or more address 
spaces in the scope of the resource. 

) 

specifies the end of the resource(s) description. 

Note: The parameters qname addr, mame addr, type of control, mame length, and the 
scope can be repeated within a single set of parentheses to indicate multiple resources. 
These parameters can be repeated until there is a maximum of 255 characters including 
the parentheses. 

,RET = CHNG 
,RET=HAVE 
,RET = TEST 
,RET = USE 
,RET = NONE 

specifies the type of request for all of the resources named above. 

CHNG - the status of the resource specified is to be changed from shared to exclusive 
control. 

HAVE - control of the resources is requested conditionally; that is, control is requested 
only if a request has not been made previously for the same task. 
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TEST - the availability of the resources is to be tested, but control of the resources is 
not requested. 

USE - control of the resources is to be assigned to the active task only if the resources 
are immediately available. If any of the resources are not available, the active 
task is not placed in a wait condition. 

NONE - control of all the resources is unconditionally requested. 

,RELATED = va/Me 

specifies information used to self-document macro instructions by 'relating' functions or 
services to corresponding functions or services. The format and contents of the 
information specified are at the discretion of the user, and may be any valid coding 
values. 

The RELATED parameter is available on macro instructions that provide opposite 
services (for example, ATTACH/DETAGH, GETMAIN/FREEMAIN, and 
LOAD/DELETE), and on macro instructions that relate to previous occurrences of the 
same macro instructions (for example, CHAP and ESTAE). 

The RELATED parameter may be used, for example, as follows: 

ENQUEUE ENQ ( MAJOR, MINOR, S, 8, STEP ) , X 
RELATED= ( DEQUEUE , ' OBTAIN RESOURCE ' ) 

DEQUEUE DEQ ( MAJOR , MINOR , 8 , STEP ) , X 
RELATED= ( ENQUEUE , ' RELEASE RESOURCE ' ) 

Return codes are provided by the control program only if you specify RET = TEST, 
RET = USE, RET = CHNG, or RET = HAVE; otherwise, return of the task to the active 
condition indicates that control of the resource has been assigned (or previously assigned) to the 
task. If all return codes for the resources named in the ENQ macro instruction are 0, register 
15 contains 0, If any of the return codes are not 0, register 15 contains the address of a storage 
area containing the return codes, as shown in Figure 52. The return codes are placed in the 
parameter Ust resulting from the macro expansion in the same sequence as the resource names 
in the ENQ macro instruction. The return codes are shown in Figure 53. 
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Return codes are 
1 2 bytes apart, 
starting 3 bytes 
from the address 
in register 15. 



RC N 



Figure 52. Return Code Area Used by ENQ 



Hexadecunal 

Code Meaning 

0 For RET = 

For RET = 
For RET = 



4 

8 

14 
18 



=TEST, the resource was immediately available. 

=USE or RET = HAVE, control of the resource has been assigned to the active task. 
=CHNG, the status of the resource has been changed to exclusive. 



For RET = TEST or RET = USE, the resource is not immediately available. 
For RET = CHNG, the status cannot be changed to exclusive. 

For RET = TEST, RET = USE, or RET = HAVE, this task has made a previous request for control of 
the same resource and this task has control of the resource. 

If bit 3 of the first byte of this entry in the ENQ parameter list is on, this task has shared control of the 
resource; if bit 3 is off, this task has exclusive control. 

For RET = CHNG, the resource was not queued or was not previously requested by the requesting task. 

This task has made a previous request for control of the same resource, and this task does not have 
control of resource. 

For RET = HAVE or RET = USE, the limit for the number of concurrent resource requests has been 
reached. The task does not have control of the resource unless some previous ENQ request caused the 
task to obtain control of the resource. 



Figure 53. ENQ Return Codes 
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Example 1 



Operation: Conditionally request shared control of a serially reusable resource that is known 
only within the address space (STEP). The resource is only to be obtained if immediately 
available. The resource will be used for read-only purposes. The length of mame is allowed to 
default. 

ENQ (MAJ0R1,MIN0R1,S, ,STEP) ,RET=USE 

Example 2 

Operation: Unconditionally request exclusive control of 3 resources. The scope of each 
resource differs (STEP, SYSTEM, and SYSTEMS respectively). The mame length of the first 
resource is 3 characters and the mame length of the third resource is 8 characters. Allow the 
rname length of the second resource to default to its assembled length. 

ENQ (MAJOR4,MINOR4,E,3, ,MAJOR2,MINOR2, , ^SYSTEM, X 

MA J0R3 , MIN0R3 , E , 8 , SYSTEMS ) 
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ENQ (List Fonn) 



Use the list form of ENQ to construct a control program parameter list. Any number of 
resources can be specified in the ENQ macro instruction; therefore, the number of qname, 
rname, and scope combinations in the list form the ENQ macro instruction must be equal to the 
maximum number of qname, rname, and scope combinations in any execute form of the macro 
instruction that refers to that list form. 

The list form of the ENQ macro instruction is written as follows: 



name 



h 

ENQ 
b 



name: symbol. Begin name in column 1. 
One or more blanks must precede ENQ. 

One or more blanks must follow ENQ. 



( 



qname addr 
rname addr 

.S 

jrname length 



qname addr: A-type address. 
rname addr: A-type address. 

Default: E 



rname length: symbol or decimal digit. 
Default: assembled length of rname 



,STEP 

.SYSTEM 

.SYSTEMS 



Default: STEP 



,RET = CHNG 
,RET = HAVE 
,RET=TEST 
,RET=USE 
,RET=NONE 

.RELATED = va/we 
,MF=L 



Default: RET = NONE 



value: any valid macro keyword specification. 



The parameters are explained under the standard form of the ENQ macro instruction, with the 
following exception: 

,]VIF=L 

specifies the Ust form of the ENQ macro instruction. 
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ENQ (Execute Form) 



A remote control program parameter list is used! in, and can be modified by, the execute form 
of the ENQ macro instruction. The parameter list can be generated by the list form of ENQ. 

The execute form of the ENQ macro instruction is written as follows: 



b 

ENQ 
b 



name: symbol. Begin /lome in column 1. 
One or more blanks must precede ENQ. 

One or more blanks must follow ENQ. 



( 

qname addr 

rname addr 
» 

,S 

,rname length 



Note: ( and ) are the beginning and end of a parameter list. The entire list is 
optional. If nothing in the list is desired, then (, ), and all parameters between 
( and ) should not be specified. If something in the Ust is desired, then (, ), and 
all parameters in the list should be specified as indicated at the left. 

qname addr: RX-type address, or register (2) - (12). 

rname addr: RX-type address, or register (2) - (12). 

Defanlt: E 



rname length: symbol, decimal digit, or register (2) - (12). 



,STEP 

,SYSTEM 

.SYSTEMS 

) 

,RET = CHNG 
,RET=HAVE 
,RET=TEST 
,RET = USE 
,RET = NONE 

,RELATED = vc/Me 
M^ = {^,ctrladdr) 



Default: STEP 

Note: See note opposite ( above. 
Default: RET = NONE 



value: any valid macro keyword specification. 
Ctrl addr: RXrtype address, or register (1) - (12). 



The parameters are explained under the standard form of the ENQ macro instruction, with the 
following exception: 

,MF = (E,c?r/ai/f/r) 

specifies the execute form of the ENQ macro instruction using a remote control program 
parameter list. 
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ESPIE - Extended SPIE 



The ESPIE macro instruction extends the function of the SPIE (specify program interruption 
exits) macro instruction to callers in 31 -bit addressing mode. Callers in either 24-bit or 31 -bit 
addressing mode can issue the ESPIE macro instruction. Only callers in 24-bit addressing mode 
can issue the SPIE macro instruction. For additional information concerning the relationship 
between the SPIE and the ESPIE macro instructions, see the section "Interruption Services" in 
Part I. 

The ESPIE macro instruction performs the following functions using the options specified: 

• Establishes an ESPIE environment (that is, identifies the interruption types that are to 
cause entry to the ESPIE exit routine) by executing the SET option of the ESPIE macro 
instruction. 

• Deletes an ESPIE environment (that is, cancels the current SPIE/ESPIE environment) by 
executing the RESET option of the ESPIE macro instruction. 

• Determines the current SPIE/ESPIE environment by executing the TEST option of the 
ESPIE macro instruction. 

SET Option 



The SET option of the ESPIE macro instruction is written as follows: 



name 

b 

ESPIE 
b 


name: symbol. Begin name in column 1. 
One or more blanks must precede ESPIE. 

One or more blanks must follow ESPIE. 


SET 




,exit addr 


exit addr: A- type address, or register (2) - (12). 


^interruptions) 


interruptions: decimal digits 1-15 and expressed as: 




single values: (2, 3, 4, 7, 8, 9, 10) 




ranges of values: ((2, 4), (7, 10)) 




combinations: (2, 3, 4, (7, 10)) 


^ARAM = list addr 


list addr: A-type address or register (2) - (12). 



The parameters are explained as follows: 
SET 

indicates that an ESPIE environment is to be established. 
^xit addr 

specifies the address of the exit routine to be given control when program interruptions of 
the type specified by interruptions occur. The exit routine receives control in the same 
addressing mode as the issuer of the ESPIE macro instruction. 
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,( interruptions) 

indicates the interruption types that are being trapped. The interruption types are: 



Number 


InterrnptioD Type 


1 


Operation 


2 


Privileged operation 


3 


Execute 


4 


Protection 


5 


Addressing 


6 


Specification 


7 


Data 


8 


Fixed-point overflow (maskable) 


9 


Fixed-point divide 


10 


Decimal overflow (maskable) 


11 


Decimal divide 


12 


Exponent overflow 


13 


Exponent underflow (maskable) 


14 


Significance (maskable) 


15 


Floating-point divide 



These interruption types can be designated as one or more single numbers, as one or more 
pairs of numbers (designating ranges of values), or as any combination of the two forms. 
For example, (4,8) indicates interruption types 4 and 8; ((4,8)) indicates interruption types 
4 through 8. 

If a program interruption type is maskable, the corresponding program mask bit in the 
PSW is set to 1. If a maskable interruption is not specified, the corresponding bit in the 
PSW is set to 0. Interruption types not specified above (except for type 17, which is 
described in SPL: System Macros and Facilities) are handled by the control program. 
The control program forces an abend with the program check as the completion code. If 
an ESTAE-type recovery routine is also active, the SDWA indicates a system-forced 
abnormal termination. The registers at the time of the error are those of the control 
program. 

Note: For both ESPIE and SPIE - If you are using vector instructions and an exception 
of 8, 12, 13, 14, or 15 occurs, your recovery routine can check the exception extension 
code (the first byte of the two-byte interruption code in the EPIE or PIE) to determine 
whether the exception was a vector or scalar type of exception. 

fPAEiAM'= list addr 

specifies the fullword-address of a parameter list that is to be passed by the caller to the 
exit routine. 

On return from the SET option of the ESPIE macro instruction, the registers contain the 
following information: 

R^jtster Content 



0 Unpredictable 

1 Token representing the previously active SPIE/ESPIE environment 
2-13 Unchanged 

14 Unpredictable 

15 Return code of 0 
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Example 1 



Operation: Give control to an exit routine for interruption types 1 and 4. EXIT is the location 
of the exit routine to be given control and PARMLIST is the location of the user parameter list 
to be used by the exit routine. 

ESPIE SET, EXIT, (1,4) , PARAM=PARMLIST 

RESET Option 

The RESET option of thfe ESPIE macro cancels the current SPIE/ESPIE environment and 
re-establishes tihe previously active SPIE/ESPIE environment identified by the token specified. 



The RESET option of the ESPIE macro instruction is written as follows: 



name 


name: symbol. Begin name in column 1. 


b 


One or more blanks must precede ESPIE. 


ESPIE 




b 


One or more blanks must follow ESPIE. 


RESET 




,token 


token: RX-type address, or register (1), (2) - (12). 



The parameters are explained as follows: 
RESET 

indicates that the current ESPIE environment is to be deleted and the previously active 
SPIE/ESPIE environment specified by token is to be re-estabUshed. 

,token 

specifies a fuUword that contains a token representing the previously active SPIE/ESPIE 
environment. This is the same token that ESPIE processing returned to the caller when 
the ESPIE environment was estabUshed using the SET option of the ESPIE macro 
instruction. 

If the token is zero, all SPIEs and ESPIEs are deleted. 
On return from ESPIE RESET, the contents of the registers are as follows: 

Register Contents 



0 Unpredictable 

1 Token identifying the new active SPIE/ESPIE environment 
2-13 Unchanged 

14 Unpredictable 

15 Return code of 0 
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Example 1 



Operation: Cancel the current SPIE/ESPIE environment and restore the SPIE/ESPIE 
environment represented by the contents of TOKEN. 

ESPIE RESET, TOKEN 

TEST Option 

The TEST option of the ESPIE macro instruction determines the active SPIE/ESPIE 
environment and returns the information in a four-byte parameter Hst. 



The TEST option of the ESPIE macro instruction is written as follows: 



neane 


name: symbol. Begin «awe in column 1. 


b 


One or more blanks must precede ESPIE. 


ESPIE 




b 


One or more blanks must follow ESPIE. 


TEST 




^arm addr 


parm addr: RX-type address, or register (1), (2) - (12). 



The parameters are explained as follows: 
TEST 

indicates a request for information concerning the active or current SPIE/ESPIE 
environment. ESPIE processing returns this information to the caller in a four-word 
parameter Ust located at parm addr. 

,parm addr 

specifies the address of a four-word parameter Ust aUgned on a fullword boundary. The 
parameter list has the following form: 

Word Content 



0 Address of the user-exit routine (31 -bit address with the l^h-order bit set to 0) 

1 Address of the user-defined parameter list 

2 Mask of program interruption types (Note: Bit 1 corresponds to interrupt code 1, bit 2 to interrupt code 
2, and so on.) 

3 Zero 
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On return from ESPIE TEST, the registers contain the following information: 

Register Contents 

0 Unpredictable 

1-13 Unchanged 

14 Unpredictable 

15 Return code as follows: 
Code Meaning 

0 An ESPIE exit is active and the four-word parameter list contains the information described under 
the parm addr parameter of the ESPIE macro instruction. 

4 A SPIE exit is active and word 1 of the parameter list contains the address of the current PICA. 
Words 0, 2, and 3 of the parameter list are unpredictable. 

8 A SPIE or ESPIE exit is not active. All the words of the parameter list are unpredictable. 

Example 1 

Operation: Identify the active SPIE/ESPIE environment. Return the information about the 
exit routine in the four-word parameter list, PARMLIST. Also return, in register 15, an 
indicator of whether a SPIE, ESPIE, or neither is active. 

ESPIE TEST, PARMLIST 



ESPIE - Extended SPIE 185 



ESPIE (List Form) 



The list form of the ESPIE macro instruction builds a non-executable problem program 
parameter list that can be referred to or modified by the execute form of the ESPIE macro 
instruction. 

The list form of the ESPIE macro instruction is written as follows: 



name name: symbol. Begin name in column 1. 

b One or more blanks must precede ESPIE. 

ESPIE 

b One or more blanks must follow ESPIE. 

SET 

,exit addr exit addr: A-type address. 

Note: This parameter must be specified on either the list or the execute form of 
the macro instruction. 

,(interrt^tions) interruptions: decimal digit 1-lS and expressed as: 

single values: (2, 3, 4, 7, 8, 9, 10) 
range of values: ((2, 4), (7, 10)) 
combinations: (2, 3, 4, (7, 10)) 

,FARAM = list addr list addr: A-type address. 

,MF = L 



The parameters are explained under the standard form of the ESPIE macro instruction with the 
following exception: 

,MF = L 

specifies the list form of the ESPIE macro instruction. 



Example 1 

Operation: Build a non-executable problem program parameter list that will cause control to 
be transferred to the exit routine, EXIT for the interruption types specified in the execute form 
of the macro instruction. Provide the address of the user parameter list, PARMLIST. 

LISTl ESPIE SET, EXIT, ,PARAM=PARMLIST,MF=L 
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ESPIE (Execute Form) 



The execute form of the ESPIE macro instruction can refer to and modify the parameter hst 
constructed by the list form of the ESPIE macro instruction. 

The execute form of the ESPIE macro instruction is written as follows: 



name 

b 

ESPIE 
b 



name: symbol. Begin name in column 1 . 
One or more blanks must precede ESPIE. 

One or more blanks must follow ESPIE. 



SET 



,exit addr 



^interruptions) 



exit addr: RX-type address or register (2) - (12). 

Note: This parameter must be specified on either the list or the execute form of 
the macro instruction. 

interruptions: decimal digit 1-1 S and expressed as: 



,f ARAM = list addr 
,MF = (^ctrladdr) 



single values: (2, 3, 4, 7, 8, 9, 10) 
range of values: ((2, 4), (7, 10)) 
combinations: (2, 3, 4, (7, 10)) 

list addr: RX-type address or register (2) - (12). 
Ctrl addr: RX-type address, or register (1), (2) - (12). 



The parameters are explained under the standard form of the ESPIE macro instruction with the 
following exception: 

,MF = (E,ctrladdr) 

specifies the execute form of the ESPIE macro instruction using a remote control program 
parameter list. 



Example 1 

Operation: Give control to a user exit routine for interruption types 1, 4, 6, 7, and 8. The exit 
routine address and the address of a user parameter list for the exit routine are provided in a 
remote control program parameter list at LISTl. 

ESPIE SET, , (1,4, (6,8) ) ,MF=(E, LISTl) 
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ESTAE — Extended Specify Task Abnormal Exit 



This macro can be assembled compatibly between MVS/XA and MVS/370 through the use of 
the SPLEVEL macro instruction. Default processing will result in an expansion of the macro 
that operates only with MVS/XA. See the topic "Selecting the Macro Level" for additional 
information. 

If your program is to execute in 31 -bit addressing mode, you must use the MVS/XA version of 
this macro instruction. ESTAE exits and retry routines execute in the same address mode as 
the program that issues the ESTAE macro instruction. 

The ESTAE macro instruction provides recovery capability facilities. Issuance of the ESTAE 
macro instruction or ATTACH with the STAT (specify task abnormal interrupts) or ESTAI 
(extended STAI) option allows the user to intercept a scheduled ABEND. Control is given to a 
user specified exit routine in which the user may perform pre-termination processing, diagnose 
the cause of ABEND, and specify a retry address if he wishes to avoid the termination. These 
exits operate in both problem program and supervisor modes. 

The standard fonn of the ESTAE macro instruction is written as follows: 



name 

b 

ESTAE 
b 


name: symbol. Begin name in column 1. 
One or more blanks must precede ESTAE. 

One or more blanks must follow ESTAE. 


exit addr 
0 


exit addr: A-type address, or register (2) - (12). 


,CT 


Default: CT 


,ov 




^K^iPCbA=list addr 


list addr: A-type address, or register (2) - (12). 


,XCTL = NO 


Default: XCTL = NO 


,XCTL = YES 




,PURGE=NONE 


Default: PURGE = NONE 


,PURGE = QUIESCE 




,PURGE = HALT 




,ASYNCH = YES 


Default: ASYNCH = YES 


,ASYNCH = NO 




,TERM==NO 


Default: TERM = NO 


,TERM = YES 




.RELATED = va/«e 


value: any valid macro keyword specification. 



The parameters are explained as follows: 

exit addr 
0 

specifies the address of an ESTAE exit routine to be entered if the task issuing this macro 
instruction terminates abnormally. If 0 is specified, the most recent ESTAE exit is 
canceled. 
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,CT 
,OV 

specifies the creation of a new ESTAE exit (CT) or indicates that parameters passed in 
this ESTAE macro instruction are to overlay the data contained in the previous ESTAE 
exit (OV). 



,PARAM = /isf addr 

specifies the address of a user-defined parameter list containing data to be used by the 
ESTAE exit routine when it is scheduled for execution. 



,XCTL=NO 
,XCTL = YES 

specifies that the ESTAE macro instruction will be canceled (NO) or will not be canceled 
(YES) if an XCTL macro instruction is issued by this program. 

,PURGE = NONE 
,PURGE = QUIESCE 
,PURGE = HALT 

specifies that all outstanding requests for I/O operations will not be saved when the 
ESTAE exit is taken (HALT), that I/O processing will be allowed to continue normally 
when the ESTAE exit is taken (NONE), or that all outstanding requests for I/O 
operations will be saved when the ESTAE exit is taken (QUIESCE). If QUIESCE is 
specified, the user's retry routine can restore the outstanding I/O requests. 

Note: If PURGE = NONE is specified, all control blocks affected by input/output 
processing may continue to change during ESTAE exit routine processing. 

If PURGE = NONE is specified and the ABEND was originally scheduled because of an 
error in input/output processing, an ABEND recursion will develop when an input/output 
interruption occurs, even if the exit routine is in progress. Thus, it will appear that the 
exit routine failed when, in reaUty, input/output processing was the cause of the failure. 

Do not use PURGE = HALT to stop processing a data set if you expect to continue 
reading the data set at a different point. 

ISAM Notes: If ISAM is being used and PURGE = HALT is specified or PURGE = QUIESCE 
is specified but I/O is not restored: 

• Only the input/output event on which the purge is done will be posted. Subsequent event 
control blocks (ECBs) will not be posted. 

• The ISAM check routine will treat purged I/O as normal I/O. 

• Part of the data set may be destroyed if the data set is being updated or added to when the 
failure occurred. 

,ASYNCH = YES 
,ASYNCH = NO 

specifies that asynchronous exit processing will be allowed (YES) or prohibited (NO) 
while the user's ESTAE exit is executing. 
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ASYNCH = YES must be coded if: 



• Any supervisor services that require asynchronous interruptions to complete their 
normal processing are going to be requested by the ESTAE exit routine. 

• PURGE = QUIESCE is specified for any access method that requires asynchronous 
interruptions to complete normal input/output processing. 

• PURGE = NONE is specified and the CHECK macro instruction is issued in the 
ESTAE exit routine for any access method that requires asynchronous interruptions 
to complete normal input/output processing. 

Note: If ASYNCH = YES is specified and the ABEND was originally scheduled because 
of an error in asynchronous exit handling, an ABEND recursion will develop when an 
asynchronous exit handUng was the cause of the failure. 

,TERM = NO 
,TERM = YES 

specifies that the exit routine associated with the ESTAE request will be scheduled (YES) 
or will not be scheduled (NO), in addition to normal ESTAE processing, in the following 
situations: 

• Cancel by operator. 

• Forced logoff. 

• Expiration of job step timer. 

• Exceeding of wait time limit for job step. 

• ABEND condition because of DETACH of an incomplete subtask when the STAE 
option was not specified on the DETACH. 

• ABEND of the attaching task when the ESTAE macro instruction was issued by a 
subtask. 

• ABEND of job step task when a non-job step task requested ABEND with the STEP 
option. 

When the exit routine is entered because of one of the preceding reasons, retry will not be 
permitted. If dump is requested at the time of ABEND, it is taken prior to entry into the 
exits. 

Note: If DETACH was issued with the STAE parameter, the following will occur for the task 
to be detached: 

• All ESTAE exits will be entered. 

• The most recently established STAE exit will be entered. 

• All STAI/ESTAI exits will be entered unless return code 16 is returned from one of the 
STAI exits. 

In these cases, entry to the exit is prior to dumping and retry will not be permitted. 
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,RELATED = va/Me 

specifies information used to self-document riacro instructions by 'relating' functions or 
services to corresponding functions or services. The format and contents of the 
information specified are at the discretion of the user, and may be any valid coding 
values. 

The RELATED parameter is available on macro instructions that provide opposite 
services (for example, ATTACH/DETACH, GETMAIN/FREEMAIN, and 
LOAD/DELETE), and on macro instructions that relate to previous occurrences of the 
same macro instructions (for example, CHAP and ESTAE). 

The RELATED parameter may be used, for example, as follows: 

DEFESTAE ESTAE ( 4 ) , CT , PARAM= ( 2 ) , RELATED= ( DELESTAE , 
' DELETE ESTAE ' ) 



DELESTAE ESTAE 0 , RELATED= ( DEFESTAE , ' DEFINE ESTAE ' ) 

Note: This macro instruction will fit on one line when coded, so there is no need for a 
continuation indicator. 

Control is returned to the instruction following the ESTAE macro instruction. When control is 
returned, register 15 contains one of the following return codes: 

Hexadedmal 



Code Meaning 

00 Successful completion of ESTAE request. 

04 ESTAE OV was specified with a valid exit address, but the current exit is either nonexistent, not owned 

by the user's RB, or is not an ESTAE exit. 

OC Cancel (an exit address equal to zero) was specified and either there are no exits for this TCB, the most 

recent exit is not owned by the caller, or the most recent exit is not as ESTAE exit. 

10 An unexpected error was encountered while processing this request. 

14 ESTAE was unable to obtain storage for an SCB. 



Example 1 

Operation: Request an overlay of the existing ESTAE recovery exit (at ADDR), with the 
following options: parameter list is as PLIST, I/O will be halted, no asynchronous exits will be 
taken, ownership will be transferred to the new request block resulting from any XCTL macro 
instructions. 

ESTAE ADDR , OV , PARAM=PLIST , XCTL=YES , PURGE=HALT , ASYNCH=NO 

Example 2 

Operation: Provide the pointer to the recovery code in the register called EXITPTR, and the 

address of the ESTAE exit parameter list in register 9. Register 8 points to the area where the 
ESTAE parameter list (created with the MF = L option) was moved. 

ESTAE (EXITPTR) ,PARAM=(9) ,MF=(E, (8) ) 
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ESTAE (List Form) 



The list form of the ESTAE macro instruction is used to construct a remote control program 
parameter list. 

The list form of the ESTAE macro instruction is written as follows: 



ncime 


name: symbol. Begin wame in column 1. 


b 


One or more blanks must precede ESTAE. 






b 


One or more blanks must follow ESTAE. 


exit addr 
0 


exit addr: A-type address. 


,1?KRAM = list addr 


list addr: A-type address. 


,PURGE = NONE 
,PURGE = QUIESCE 
,PURGE = HALT 


Default: PURGE = NONE 


,ASYNCH=YES 
,ASYNCH = NO 


Default: ASYNCH = YES 


,TERM = NO 
,TERM = YES 


Default: TERM = NO 


,RELATED = va/Me 


value: any valid macro keyword specification. 


,MF = L 





The parameters are explained under the standard form of the ESTAE macro instruction, with 
the following exception: 

,MF=L 

specifies the list form of the ESTAE macro instruction. 
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ESTAE (Execute Fonn) 



A remote control program parameter list is used in, and can be modified by, the execute form 
of the ESTAE macro instruction. The control program parameter list can be generated by the 
list form of the ESTAE macro instruction. If the user desires to dynamically change the 
contents of the remote ESTAE parameter list, he may do so by coding a new exit address 
and/or a new parameter list address. If exit address or PARAM is coded, only the associated 
field in the remote ESTAE parameter list will be changed. The other field will remain as it was 
before the current ESTAE request was made. 

The execute form of the ESTAE macro instruction is written as follows: 



name 


name: symbol. Begin name in column 1. 


D 


One or more blsnks must precede ESTAE. 


ESTAE 




b 


One or more blanks must follow ESTAE. 


exit addr 
0 


exit addr: RX-type address, or register (2) - (12). 


,CT 

,cv 




,PARAM = /Mr arfrfr 


list addr: RX-type address, or register (2) - (12). 


,XCTL = NO 
,XCTL=YES 




,PURGE = NONE 
,PURGE = QUIESCE 
.PURGE = HALT 




,ASYNCH=YES 
,ASYNCH=NO 




.TERM = NO 
.TERM = YES 




.RELATED = va/Me 


value: any valid macro keyword specification. 


.MF=(E,c//-/ addr) 


Ctrl addr: RX-type address, or register (1) or (2) - (12). 



The parameters are explained under the standard form of the ESTAE macro instruction, with 
the following exception: 

,MF=(E,cfr/a«/</r) 

specifies the execute form of the ESTAE macro instruction using a remote control 
program parameter list. 



ESTAE (Execute Form) 193 



EVENTS — Wait for One or More Events to Complete 



This macro can be assembled compatibly between MVS/XA and MVS/370 through the use of 
the SPLEVEL macro instruction. Default processing will result in an expansion of the macro 
that operates only with MVS/XA. See the topic "Selecting the Macro Level" for additional 
information. 

If your program is to execute in 31 -bit addressing mode, you must use the MVS/XA version of 
this macro instruction. 

The EVENTS macro instruction is a functional specialization of the WAIT ECBLIST = macro 
facility with the advantages of notifying the program that events have completed and the order 
in which they completed. 

The macro performs the following functions: 

• Creates and deletes EVENTS tables. 

• Initializes and maintains a list of completed event control blocks. 

• Provides for single or multiple ECB processing. 

For a detailed explanation of how to use EVENTS to perform these functions see "Using the 
EVENTS Macro Instruction" in this section. 



The EVENTS macro instruction is written as follows: 



name 


name: symbol. Begin name in column 1. 


b 


One or more blanks must precede EVENTS. 


EVENTS 




b 


One or more blanks must follow EVENTS. 


ENTRIES = « 

ENTRIES = DEL,TABLE = 
TABLE = table address 


n: variable, decimal digit 1-32,767. 
table address table address: symbol, RX-type address, or register (2) - (12). 

Note: If ENTRIES = « or ENTRIES = DEL, TABLE = table address is not 
specified, no other parameter should be specified. 


,WAIT=NO 
,WAIT=YES 


Default: None. 


,ECB = ecb address 
,LAST = last address 


ecb address: symbol, RX-type address, or register (2) - (12). 

last address: symbol, RX-type address, or register (2) - (12). 

Note: Optional parameters are only valid when TABLE = table address is the 

only required parameter specified. 



The parameters are explained as follows: 
ENTRIES = « 

n is a decimal number from 1 to 32,767 that specifies the maximiun number of completed 
ECB addresses that can be processed in an EVENTS table concurrentiy. 

Note: When this parameter is specified no other parameter should be specified. 

ENTRIES = DEL,TABLE = table address 

specifies that the EVENTS table whose address is specified by TABLE = table address is 
to be deleted. The user is responsible for deleting all of the tables he creates; however, all 
existing tables are automatically freed at task termination. 



194 Supervisor Services and Macro Instructions 



Notes: 



1. When this parameter is specified no other parameter should be specified. 

2. table address specifies a storage location below 16 megabytes. 

TABLE - table address 

specifies either a register number or the address of a word containing the address of the 
EVENTS table associated with the request. The address specified with the operand 
TABLE must be that of an EVENTS table created by this task. 

Note: table address specifies a storage location below 16 megabytes. 

,wArr=NO 

,WAIT=YES 

specifies whether or not to put the issuing program in a wait state when there are no 
completed events in the' EVENTS table (specified by the TABLE = parameter). 

,ECB = ec^7 address 

specifies either a register number or the address of a word containing the address of an 
event control block. The EVENTS macro instruction should be used to initialize any 
event-type ECB. To avoid the accidental destruction of bit settings by a system service 
such as an access method, the ECB should be initialized after the system service that will 
post the ECB has been initiated (thus making the ECB eligible for posting) and before the 
EVENTS macro is issued to wait on the EVENTS table. 

Notes: 

1. Register 1 should not be specified for the ECB address. 

2. This parameter may not be specified with the LAST= parameter. 

3. If only ECB initialization is being requested, neither WAIT— NO nor WAIT= YES 
should be specified, to prevent any unnecessary WAIT processing from occurring. 

,LAST = last address 

specifies either a register number or the address of a word containing the address of the 
last EVENT parameter Ust entry processed. 

Notes: 

1. Register 1 should not be specified for the LAST address. 

2. This parameter should not be specified with the ECB = parameter. 

3. last address specifies a storage location below 16 megabytes. 
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Using the EVENTS Macro Instruction 



The following explains the different uses of EVENTS: 

• Creating EVENTS Tables — When ENTRIES = n is specified, the system creates an 

EVENTS table with "n" entries for completed ECB addresses. This table is queued on the 
EVENTS table queue associated with the task. (There is no limit to the number of 
EVENTS tables that can be queued for a single task.) The address of the EVENTS table is 
returned to the user in register 1. See Figure 54. 



Register 1 



EVENTS Table 



ENTRY1 



ENTRY2 



Header Section 



\ Variable Length 
/ Entry Section 



ENTRYn-1 



ENTRYn 



J 



Figure 54. Creating a Table 

• Deleting EVENTS Tables - When ENTRIES = DEL,TABLE = table address is specified, 
the EVENTS table whose address is specified by the TABLE = table address parameter shall 
be deleted. The address specified with the TABLE operand must be that of an EVENTS 
table created by this task. The user is responsible for deleting all of the tables he creates; 
however, all existing tables are automatically freed at task termination. 

• Initializing ECBs — When an ECB is created, bits 0 (wait bit) and bit 1 (post bit) must be 
set to zero. When an EVENTS ECB = macro instruction is issued, bit 0 of the associated 
event control block is set to 1. When a POST macro instruction is issued, bit 1 of the 
associated event control block is set to 1 and bit 0 is set to 0. If the ECB is reused, bit 0 
and bit 1 must be set to zero before either a WAIT, EVENTS ECB = , or POST macro 
instruction can be specified. If, however, the bits are set to zero before the ECB has been 
posted, any task waiting for that ECB to be posted will remain in wait state. 



• Maintaining a List of Completed EVENT Control Blocks — After the ECB has been 
initialized the POST macro sets the complete bit and puts the address of the completed 
ECB in the EVENTS table. 
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• Providing Single or Multiple ECB Processing — When the WAIT parameter is specified and 
there are completed ECBs in the EVENTS table, the address of the parameter list is 
returned in register 1. The parameter list has the following format: 



Register 1 







ECB1 




— > 






ECB2 ^ 




— > 






ECBm-1 




— > 


1 




ECBm 


— > 



Figure 55. Parameter List Format 



The parameter Ust contains completed ECB addresses in post occurrence order. The high order 
bit of the last word in the list is set to 1. The user may choose to process the entire list (see 
LAST parameter) or one event at a time by successive EVENTS requests with the WAIT = 
option. 

However, if WAIT = NO is specified and no ECBs are posted in the EVENTS table, register 1 
contains a zero when the user receives control. 

When a user has processed more than one ECB in the parameter list returned from the previous 
EVENTS WAIT= macro, the LAST= parameter should be used to indicate the last ECB 
processed. The EVENTS macro removes from the parameter list all entries from the first thru 
the last specified by LAST, and then completes processing the request according to the WAIT = 
specification. 

In the illustration that follows, ECBs 6 through 10 were posted to the parameter list while the 
user was processing 1 through 5. 
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EVENTS TABLE-table address. WAIT-YES 



Register 1 





— > 


ECB1 




— ► 


ECB2 




— > 


ECB3 




— > 


ECB4 


1 




ECB5 



(Load register 2 with address of the last entry processed.) 



EVENTS TABLE=table address, WAIT=YES. LAST=(2) 



Register 1 





— > 


ECB6 




— > 


ECB7 




— ► 


ECB8 




— >■ 


ECB9 


1 


— ► 


ECB10 



Figure 56. Posting the Parameter List 
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This figure demonstrates processing one event at a time. 



Issuing EVENTS TABLE=table address, WAIT=YES for the 
first time will Initiate: 



Register 1 



Parameter List 





— > 


ECB1 




— > 


ECB2 




— > 


ECB3 




— ► 


ECB4 


1 


— > 


ECB5 



The second time that EVENTS TABLE=table address. WAIT=YES 
is issued will initiate: 



Register 1 



Parameter List 





— > 


ECB2 




— >► 


ECB3 






ECB4 




— > 


1 




ECB5 


— ► 



Figure 57. Processing One Event At a Time 
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Example 1 



The following shows total processing via EVENTS. 
EVENTS and ECB Initialization 



START 

EVENTS ENTRIES=1000 

ST Rl^TABADD 

WRITE ECBA 

LA R2,ECBA 

EVENTS TABLE=TABADD , ECB= ( R2 ) 

Parameter List Processang 

BEGIN 

EVENTS TABLE=TABADD , WAIT=YES 

LR R3,R1 PARMLIST ADDR 

B L00P2 GO TO PROCESS ECB 

LOOP 1 EVENTS TABLE-TABADD , WAIT=YES , LAST= { R3 ) 

LR R3,R1 SAVE POINTER 

L00P2 EQU * PROCESS COMPLETED EVENTS 

TM 0(R3),X'80' TEST FOR MORE EVENTS 

BO LOOPl IF NONE, GO WAIT 

LA R3 , 4 ( , R3 ) GET NEXT ENTRY 

B L00P2 GO PROCESS NEXT ENTRY 

Deleting EVENTS Table 

EVENTS TABLE=TABADD , ENTRIES=DEL 

TABADD DS F 



Example 2 

Processing One ECB at a Time. 





EVENTS 


ENTRIES=10 




ST 


1, TABLE 


NEXTREC 


GET 


TPDATA^KEY 




ENQ 


( RESOURCE , ELEMENT ,E , , SYSTEM ) 




READ 


DECBRW , KU , , • S • , MF=E 




LA 


3,DECBRW 




EVENTS 


TABLE=TABLE,ECB=(3) ,WAIT=YES 




WRITE 


DECBRW, K,MF=E 




LA 


3, DECBRW 


RETEST 


EVENTS 


TABLE=TABLE , ECB= ( 3 ) , WAIT=NO 




LTR 


1,1 




BNZ 


NEXTREC 




B 


RETEST 


TABLE 


DS 


F 
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— Fast Path Resource Authorization Checking 



The FRACHECK macro is used to check a user's authorization for access to a resource. 
FRACHECK verifies access to those resources whose RACE profiles have been brought into 
main storage by the RACLIST faciUty. FRACHECK is a branch entered service that does not 
save registers upon entry. Registers 0-5, 14, and 15 are used by the FRACHECK macro 
instruction and are not restored. Registers 6-13 are not altered by FRACHECK. 

Note: For RACE release 1.6 and previous releases: Only callers in 24-bit addressing mode can 
issue this macro. Callers executing in 31 -bit addressing mode, who want to use the 
FRACHECK function, can code the RACROUTE macro. 

The standard form of the FRACHECK macro instruction is written as follows: 



name 

b 

FRACHECK 
b 


name: symbol. Begin name in column 1. 

One or more blanks must precede FRACHECK. 

One or more blanks must follow FRACHECK. 


ENTITY = enriO' addr 


entity addr: A-type address or register (2) - (12). 


,CLASS= 'classname' 


classname: DASDVOL or TAPEVOL. 


jCLASS = classname addr 


classrutme addr: A-type address or register (2) - (12). 


,ATTR = READ 


reg: registers (2) - (12). 


,ATTR = UPDATE 


Default: ATTR = READ 


,ATTR = CONTROL 




,ATTR = ALTER 




,ATTR = reg; 




, ACEE = acee addr 


acee addr: A-type address or register (2) - (12). 


,WK.AREA = area addr 


area addr: A-type address or register (2) - (12). 


,APPL= 'applruime' 




,AP¥h =applname addr 


applname addr: A-type address or register (2) - (12). 


jINSTLN = parm list addr 


parm list addr: A-type address or register (2) - (12). 


,RELEASE = number 


number: 1.6 or 1.7 




Default: RELEASE =1.6 



The parameters are explained as follows: 

ENT:TIY = entity addr 

specifies that RACE authorization checking is to be performed for the resource whose 
name is pointed to by the specified address. The resource name is a 6-byte volume serial 
number for CLASS = 'DASDVOL' or CLASS = 'TAPEVOL'. The name must be left 
justified and padded with blanks. The length of all other resource names is determined 
from the class descriptor tables. 

fCLASS= 'classname' 

,CLASS = classname addr 

specifies that RACF authorization checking is to be performed for a resource of the 
specified class. If an address is specified, the address must point to an 8-byte field 
containing the classname. 
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,ATTR = READ 
,ATTR- UPDATE 
,ATTR = CONTROL 
,ATTR= ALTER 
,ATTR = (reg) 

specifies the access authority required by the user or group accessing the resource: 

READ — RACF user or group can open the resource only to read. 

UPDATE — RACF user or group can open the resource to read or write. 

CONTROL — For VSAM data sets, RACF user or group has authority equivalent to 
the VSAM control password. For non-VSAM data sets and other resources, RACF 
user or group has UPDATE authority. 

ALTER — RACF user or group has total control over the resource. 

If a register is specified, the register must contain one of the following codes in the 
low-order byte of the register: 

X'02' - READ 
X'04'- UPDATE 
X'08'- CONTROL 
X'80'- ALTER 

^CE^ = acee addr 

specifies the address of the accessor control environment element (ACEE) to be used to 
check authorization and to locate the in-storage profiles (RACLIST output) for the 
specified classes. If an ACEE is specified, it is used for authorization checking. If the 
specified ACEE has an in-storage profile list for the specified class, it is used to locate the 
resource. If an ACEE is not specified or if there is no in-storage profile list for the 
specified class in the ACEE, RACF uses the TASK ACEE pointer in the extended TCB 
called the TCBSENV. Otherwise, or if the TASK ACEE pointer is zero, RACF uses the 
main ACEE to obtain the Ust of the in-storage profiles. The main ACEE is pointed to by 
the ASXBSENV field of the address space extension block. 

,WKAREA = area addr 

specifies the address of a 16 word work area to be used by FRACHECK which contains 
the following information: 

Word 13 contains the return code the FRACHECK caller receives. 

Word 14 contains the address of the in-storage profile used to determine 
authorization, or zero if no profile was found. 

Word 15 contains a value provided by a pre-processing installation exit, or zero if 
there was no pre-processing exit. 

Workarea words 13 and 14 are passed back to the FRACHECK issuer as a return code in 
register 15 (see return codes below) and a profile address in register 1, respectively. 
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, APPL == 'applname ' 

,APPL = applname addr 

specifies the name of the application requesting the authorization checking. This 
information is not used for the authorization checking process but is made available to 
the installation exit(s). If an address is specified, it should point to an 8-byte area 
containing the appUcation name, left justified and padded with blanks, if necessary, 

,INSTLN =parm list addr 

specifies the address of an area that contains information for the FRACHECK 
installation exit. This address is passed to the exit routine when the exit is given control. 
The INSTLN parameter is used by application or installation programs to pass 
information to the FRACHECK installation exit, 

,RELEASE = «Mm6er 

specifies the RACE release level of the parameter list to be generated by this macro. 

Certain parameters can be specified only with particular releases. If you specify a 
parameter with an incompatible release level, the parameter will not be accepted by the 
macro processing. An error message will be issued at assembly time. For the parameters 
that are valid for RELEASE = 1.6 and later, see Figure 58. 

The default is RELEASE = 1.6. 

When you specify the RELEASE keyword, checking is done at assembly time. 
Execution-time validation of the compatibility between the list and execute forms of the 
FRACHECK macro can be done by your specifying the CHECK subparameter on the 
execute form of the macro. 

Parameters For RELEASE » 1.6 and Later 

The RELEASE values for which a specific parameter is vahd are marked with an 'X'. 



Parameter 


RELEASE » 
1.6 


RELEASE = 
1.7 


ACEE = 


X 


X 


APPL = 


X 


X 


ATTR = 


X 


X 


CLASS = 


X 


X 


ENTITY = 


X 


X 


INSTLN- 


X 


X 


RELEASE = 


X 


X 


WKAREA = 


X 


X 



Figure 58. FRACHECK Parameters for RELEASE = 1.6 and Later 
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Return Codes and Reason Codes 



When control is returned, register 15 contains one of the following return codes: 



Hexadecimal 




Code 


Meaning 


00 


The user or group is authorized to use the resource. 


04 


The resource or classname is not defined to RACF. 


08 


The user or group is not authorized to use the resource. 


OC 


RACF is not active. 


10 


FRACHECK installation exit error occurred. 


14 


RACF CVT does not exist (RACF is not installed or insufficient level of RACF is installed). 


64 


Indicates that the CHECK subparameter of the RELEASE keyword was specified on the execute form 




of the FRACHECK macro; however, the list form of the macro does not have the proper RELEASE 




parameter. Macro processing terminates. 



FRACHECK examines the auditing and global auditing options currently in effect for the 
resource for which access authority is being determined. It sets a reason code that indicates to 
FRACHECK's caller if logging of the access attempt should be performed: 

Hexadecimal 

Code Meaning 

00 The access attempt is not within the scope of the audit or global audit specification. No logging should 

be performed. The user is either authorized or unauthorized for the resource as indicated by the 
FRACHECK return code. 

04 The access attempt is within the scope of the audit or global audit specification for that resource. 

Logging of the attempt should be performed by issuing, for example, a RACHECK for the resource for 
which authorization is being determined. RACHECK provides the necessary logging function. The user 
is either authorized or unauthorized for the resource, as indicated by the FRACHECK return code. 
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FRACHECK (List Form) 



The list form of the FRACHECK macro instruction is written as follows: 



FRACHECK 
b 



name: symbol. Begin name in column 1. 

One or more blanks must precede FRACHECK. 

One or more blanks must follow FRACHECK. 



ENTITY = entity addr 

,CLASS = 'classname' 
,CLASS = classname addr 



entity addr: A-type address. 

classname: DASDVOL or TAPEVOL. 
classname addr: A-type address. 



,ATTR = READ 
,ATTR = UPDATE 
,ATTR = CONTROL 
,ATTR= ALTER 

,ACEE = acee addr 

,WKAREA = area addr 

,APPL= 'applname' 
,APPL = applname addr 

,INSTLN = parm list addr 
.RELEASE = number 



Default: ATTR = READ 



acee addr: A-type address. 
area addr: A-type address. 

applname addr: A-type address. 
parm list addr: A-type address. 

number: 1.6 or 1.7 
Default: RELEASE =1.6 



,MF = L 



The parameters are explained under the standard form of the FRACHECK macro instruction, 
with the following exception: 

,MF=L 

specifies the list form of the FRACHECK macro instruction. 
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FRACHECK (Execute Form) 



The execute form of the FRACHECK macro instruction is written as follows: 



b 



name 



name: symbol. Begin name in column 1. 

One or more blanks must precede FRACHECK. 



FRACHECK 



b 



One or more blanks must follow FRACHECK. 



ENTITY = e«//0' addr 
jCLASS = classname addr 
,ATTR = (re^) 
,ACEE = acee addr 
,WKAREA = area addr 
,APPL = applname addr 
.INSTLN = parm list addr 



entity addr: RX-type address or register (2) - (12). 
classname addr: RX-type address or register (2) - (12). 
reg: register (2) - (12). 

acee addr: RX-type address or register (2) - (12). 
area addr: RX-type address or register (2) - (12). 
applname addr: RX-type address or register (2) - (12). 
parm list addr: RX-type address or register (2) - (12). 



,RELEASE= ('«MOT^>er,CHECK) number: 1.6 or 1.7 
.RELEASE = number Default: RELEASE = 1 .6 

.RELEASE = GCHECK) 



,MF = (E,ctrl addr) Ctrl addr: RX-type address or register (1) - (12). 



The parameters are explained under the standard form of the FRACHECK macro instruction, 
with the following exception: 

,MF=^(^yCtrl addr) 

specifies the execute form of the FRACHECK macro instruction, using a remote control 
program parameter list. 

,RELEASE = (number.CimCK) 
,RELEASE = number 
,RELEASE = (,CHECK) 

specifies the RACF release level of the parameter Ust to be generated by the is macro. 

Certain parameters can be specified only with particular releases. If you specify a 
parameter with an incompatible release level, the parameter will not be accepted by the 
macro processing. An error message will be issued at assembly time. For the parameters 
that are valid for RELEASE = 1.6 and later, see Figure 58 on page 203. 

The default is RELEASE = 1.6. 

When you specify the RELEASE keyword, checking is done at assembly time. 
Execution-time validation of the compatibiUty between the list and execute forms of the 
FRACHECK macro can be done by your specifying the CHECK subparameter on the 
execute form of the macro. 

When CHECK processing is requested, if the size of the list-form expansion is not large 
enough to accommodate all parameters defined by the RELEASE keyword on the execute 
form of the macro, the execute form of the macro will not be done. Instead, a return 
code of X'64' will be generated. 
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— Free Virtual Storage 



The FREEMAIN macro instruction releases one or more areas of virtual storage, or an entire 
virtual storage subpool, previously assigned to the active task as a result of a GETMAIN 
macro instruction. The active task is abnormally terminated if the specified virtual storage does 
not start on a doubleword boundary or, for an unconditional request, if the specified area or 
subpool is not currently allocated to the active task. Register 1 5 is set to 0 to indicate 
successful completion. For a conditional FREEMAIN, register 15 is set to 4 if the specified 
area or subpool is not currently allocated to the active task. 

In the parameters discussed below, EU, LU, and VU specify unconditional requests and result 
in the same processing as E, L, and V, respectively. The two formats for these requests are 
available to maintain compatibility with the GETMAIN formats. 

The standard form of the FREEMAIN macro instruction is written as follows: 



ncme name: symbol. Begin name in column 1 . 

b One or more blanks must precede FREEMAIN. 



FREEMAIN 



b 



One or more blanks must follow FREEMAIN. 



LC,LA = length addr 

LU,LA = length addr 

L,LA = length addr 

VC 

VU 

V 

EC,iy = length value 
E\J,L'V = length value 
E,LV = length value 
RC,LV = length value 
RC,SP= subpool nmbr 
RU,LV = length value 
RU,SP = subpool nmbr 
R,LV = length value 
R,SP = subpool nmbr 



length addr: A-type address, or register (2) - (12). 

length value: symbol, decimal digit, or register (2) - (12). If R, RC, 

or RU is specified, register (0) may also be specified. 

subpool nmbr: symbol, decimal digit 0-127, or register (2) - (12). 

If R is specified, register (0) may also be specified. 

Note: For subpool freemains, if the forms ^0,^9= subpool nmbr or 

RVJSP =std>pool nmbr or R,SP- subpool nmbr are specified, no other 

parameters except RELATED may be specified. SP= must be specified 

for subpool FREEMAINS; for other types of FREEMAIN, SP= is optional 

and defaults to SP=0. 

Note: RC and RU are the only parameters that can be used to free 
storage above 16 Mb. 



,A=addr 



addr: A-type address, or register (2) - (12). 

Note: If R, RC, or RU is coded, register (1) can also be specified. 



,SP= subpool nmbr 



sid>pool nmbr: symbol, decimal digit 0-127, or register (2) - (12). If R is 
specified above, register (0) may also be specified. 



,RELATED = va/Me 



value: any valid macro keyword specification. 
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The parameters are explained as follows: 

hC A = length addr 
LU^LA = length addr 
liJLA'= length addr 
VC 

vu 

V 

EC,LV = length value 
E\J,1jV = length value 
EJjV — length value 
^CfL\ = length value 
RCjSP = subpool nmbr 
RU,LV = length value 
RU,SP = subpool nmbr 
R,LV = length value 
R,SP = subpool nmbr 

specifies the type of FREEMAIN request: 

LC, LU, and L indicate conditional (LC) and unconditional (LU and L) list requests, and 
specify release of one or more areas of virtual storage. The length of each virtual storage 
area is indicated by the values in a Ust beginning at the address specified in the LA 
parameter. The address of each of the virtual storage areas must be provided in a 
corresponding list whose address is specified in the A parameter. All virtual storage areas 
must start on a doubleword boundary. 

VC, VU, and V indicate conditional (VC) and unconditional (VU and V) variable 
requests, and specify release of single areas of virtual storage. The address and length of 
the virtual storage area are provided at the address specified in the A parameter. 

EC, EU, and E indicate conditional (EC) and unconditional (EU and E) element requests, 
and specify release of single areas of virtual storage. The length of the single virtual 
storage area is indicated in the LV parameter. The address of the virtual storage area is 
provided at the address indicated in the A parameter. 

RC, RU, and R indicate conditional (RC) and unconditional (RU and R) register 
requests, and specify release of single areas of virtual storage from the subpool indicated, 
or specify release of the entire subpool indicated. If the release is not for the entire 
subpool, the address of the virtual storage area is indicated in the A parameter. The 
length of the area is indicated in the LV parameter. The virtual storage area must start 
on a doubleword boundary. 

Notes: 

1. A conditional request indicates that the task is not to be abnormally terminated if the 
virtual storage being freed is not allocated to the active task. However, A05-2 and 
A78-2 abends cannot be prevented. An unconditional request indicates that the task is 
to be abnormally terminated in this situation. 

2. If the address of the area to be freed is greater than 16 Mb, you must use RC or RU. 

3. Callers executing in either 24-bit or 31 -bit addressing mode can use RC or RU to free 
storage located above 16 Mb. 
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LA specifies the virtual storage address of one or more consecutive fullwords starting on a 
fuUword boundary. One word is required for each virtual storage area to be released; the 
high-order bit in the last word must be set to 1 to indicate the end of the Ust. Each word 
must contain the required length in the low-order three bytes. The fullwords in this list 
must correspond with the fullwords in the associated list specified in the A parameter. 
The words should not reside in the area to be released. If this rule is violated and if the 
words are the last allocated items on a virtual page, the whole page is returned to storage 
and the FREEMAIN abends with an 0C4. The words must not overlap the virtual 
storage area specified in the A parameter. 

LV specifies the length, in bytes, of the virtual storage area being released. The value 
should be a multiple of 8; if it is not, the control program uses the next high multiple of 
8. If R is coded, LV = (0) may be designated; the high-order byte of register 0 must 
contain the subpool number, and the low-order three bytes must contain the length (in 
this case, the SP parameter is invalid). 

,A = addr 

specifies the virtual storage address of one or more consecutive fullwords, starting on a 
fuUword boundary. The words should not reside within the area to be released. If this 
rule is violated and if the words are the last allocated items on a virtual page, the whole 
page is returned to storage and the FREEMAIN abends with an 0C4. If E, EC, EU, R, 
RC, or RU is designated, one word, which contains the address of the virtual storage area 
to be released, is required. If V, VC, or VU is coded, two words are required; the first 
word contains the address of the virtual storage area to be released, and the second word 
contains the length of the area. If L, LC, or LU is coded, one word is required for each 
virtual storage area to be released; each word contains the address of one virtual storage 
area. If R, RC, or RU is coded, any of the registers 1 through 12 can be designated, in 
which case the address of the virtual storage area, not the address of the fullword, must 
have previously been loaded into the register. 

— subpool nmbr 

specifies the subpool number of the virtual area to be released. The subpool number can 
be between 0 and 127. The SP parameter is optional and if omitted, subpool 0 is 
assumed. If R is coded, SP = (0) can be designated, in which case the subpool number 
must be previously loaded into the low-order byte of register 0. 

For subpool freemains, the SP parameter specifies the number of the subpool to be 
released and the valid range is 1 through 127. Subpool zero cannot be released. If 
R,SP = (0) is specified with no other parameters, the high-order byte of register 0 must 
contain the subpool number and the low-order 3 bytes must contain zero. 

,RELATED = va/Me 

specifies information used to self-document macro instructions by 'relating' functions or 
services to corresponding functions or services. The format and contents of the 
information specified are at the discretion of the user, and may be any vaUd coding 
values. 

The RELATED parameter is available on macro instructions that provide opposite 
services (for example, ATTACH/DETACH, GETMAIN/FREEMAIN, and 
LOAD/DELETE), and on macro instructions that relate to previous occurrences of the 
same macro instructions (for example, CHAP and ESTAE). 
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The RELATED parameter may be used, for example, as follows: 



GETl 



GETMAIN 



R , LV=4096 , RELATED= ( FREEl , 
• GET STORAGE ' ) 



FREEl 



FREEMAIN 



R,LV=4096,A=(1) , 

RELATED= ( GETl ' FREE STORAGE ' ) 



Example 1 



Example 2 



Example 3 



Note: Each of these macro instructions will fit on one line when coded, so there is no 
need for a continuation indicator. 

When control is returned, register 15 contains one of the following return codes: 



Operation: Free 400 bytes of storage from subpool 10, where the storage address is contained 
in register 1. If the storage was allocated to the task, register 15 will contain 0 on return; if the 
storage was not allocated to the task or was partially free, the status of the storage remains 
unchanged, and a 4 is returned in register 15. 

FREEMAIN RC,LV=400 ,A=( 1) ,SP=10 



Operation: Free all of subpool 3 (if any) that belongs to the current task. A return will be 
made to the caller even if there is no subpool 3 for the current task. 

FREEMAIN RU,SP=3 



Operation: Free from subpool 5 three areas of lengths 200, 800, and 32 previously obtained by 
a list type GETMAIN which placed the addresses in AREADD. If any of these areas are not 
allocated to the task, the task will be abnormally terminated. 

FREEMAIN LU , LA=LNTHLIST , A=AREAADD , SP=5 



LNTHLIST DC F ' 200 ' ,F ' 800' ,X ' 80 ' ,FL3 ' 32 ' 
AREAADD DS 3F 



Hexadecimal 
Code 



Meaning 

Virtual storage was freed. 

Not all virtual storage was freed. 



00 
04 
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FREEMAIN (List Form) 



Use the list form of the FREEMAIN macro instruction to construct a nonexecutable control 
program parameter list. 

The list form of the FREEMAIN macro instruction is written as follows: 



name 

b 

FREEMAIN 
b 


name: symbol. Begin name in column 1. 

One or more blanks must precede FREEMAIN. 

One or more blanks must follow FREEMAIN. 


LC 




LU 




L 




VC 




vu 




V 




EC 




EU 




E 




,LAl = length addr 


length addr: A-type address. 


,LV — length value 


length value: symbol or decimal digit. 




Note: LA may only be specified with. LC, LU, or L above. 




Note: LV may only be specified with EC, EU, or E above. 


,A = addr 


addr: A-type address. 


,SP = subpool nmbr 


subpool nmbr: symbol or decimal digit 0-127. 


.RELATED = va/Me 


value: any valid macro keyword specified. 


,MF = L 





The parameters are explained under the standard form of the FREEMAIN macro instruction, 
with the following exception: 

,MF-L 

specifies the list form of the FREEMAIN macro instruction. 
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FREEMAIN (Execute Form) 



A remote control program parameter list is used in, and can be modified by, the execute form 
of the FREEMAIN macro instruction. The parameter list can be generated by the list form of 
either a GETMAIN or a FREEMAIN. 

The execute form the the FREEMAIN macro instruction is written as follows: 



rume 

b 

T7DPPA>f ATXr 
u 


name: symbol. Begin name'm column 1. 

One or more blanks must precede FREEMAIN. 

One or more blanks must follow FR.EEN1AIN. 


LC 


length addr: RX-type address or register (2) - (12). 


LU 




L 


Note: LA may only be specified with LC, LU, or L above. 


VC 


Note: LV may only be specified with EC, EU, or E above. 


vu 




V 




EC 




EU 
E 




,LA = length addr 




,hY = length value 




, A = addr 


addr: RX-type address, or register (2) - (12). 


,SP =subpool nmbr 


subpool nmbr: symbol, decimal digit 0-127, or register (2) - (12). 


,RELATED = va/Me 


value: any valid macro keyword specified. 


,MF = (E,c<r/ prog) 


Ctrl prog: RX-tjrpe address, or register (1) or (2). 



The parameters are explained under the standard form of the FREEMAIN macro instruction, 
with the following exception: 

,M¥ = (^iCtrl prog) 

specifies the execute form of the FREEMAIN macro instruction using a remote control 
program parameter list. 
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— Allocate Virtual Storage 



The GETMAIN macro instruction requests the control program to allocate one or more areas 
of virtual storage to the active task. The virtual storage areas are allocated from the specified 
subpool in the virtual storage area assigned to the associated job step. The virtual storage areas 
each begin on a doubleword or page boundary and are not cleared to 0 when allocated. (The 
storage is set to zero for the initial allocation of a page.) The total of the lengths specified must 
not exceed the length available. For most subpools the storage will be released when the task 
assigned ownership terminates, or through the use of the FREEMAIN macro instructions. 

The options R, LC, LU, VC, VU, EC, or EU can be used by callers in either 24-bit or 31 -bit 
addressing mode. If one of these options is specified, storage area addresses and lengths will be 
treated as 24-bit addresses and values. The parameter Ust addresses and the pointers to the 
length and address lists in the parameter lists (if present) will be treated as 31 -bit addresses if 
the caller's addressing mode is 31 -bit; otherwise, they will be treated as 24-bit addresses. 

The options RU, RC, VRU, and VRC can be used by callers in either 24-bit or 31 -bit 
addressing mode. However, all values and addresses will be treated as 31 -bit values and 
addresses. 



The standard form of the GETMAIN macro instruction is written as follows: 



name 


name: symbol. Begin name in column 1 . 


t) 


One or more blanks must precede GETMAIN. 


GETMAIN 




b 


One or more blanks must follow GETMAIN. 


LC,LA = length aaar,A = aaar 


length addr: A-type address, or register (2) - (12). 


LU,LA = length addr,A = addr 


length value: symbol, decimal digit, or register (2) - (12). If R is 


VC,LA = length addr, A = addr 


specified, register (0) may also be specified. 


VU,LA = length addr, A = addr 


addr: A-type address, or register (2) - (12). 


EC,LV = length value,A = addr 


Note: RC, RU, VRC, or VRU must be used to allocate storage with 


EU,LV = length value,A = addr 


addresses greater than 16Mb. 


RC,LV = length value 




KV,LV = length value 




R,LV = length value 




yRC,L'V = (maximum length value. 


maximum length value: symbol, decimal, digit, or register (2) - (12). 


minimum length value) 




'VKIJ,LV = (maximum length value. 


minimum length value: symbol, decimal, digit, or register (2) - (12). 


minimum length value 




,SP = subpool nmbr 


subpool nmbr: symbol, decimal digit 0-127, or register (2) - (12). 




Note: Subpools are specified as follows: 




• LC,LU,VC,VU,EC,EU,RC,RU,VRC, and VRU use the SP parameter. 




• R with LV not equal to (0) uses the SP parameter. 




• R with LV = (0) must use register 0. The low-order three bytes of register 




0 must contain the length of the subpool, and the high-order byte must 




contain the number of the subpool. 


,BNDRY = DBLWD 


Default: BNDRY = DBLWD 


,BNDRY = PAGE 


Note: This parameter may not be specified with R^bove. 


,LOC = BELOW 


Default: LOC = RES 


,LOC = (BELOW,ANY) 


Note: This parameter can only be used with RC, RU, VRC, or VRU. 


,LOC = (ANY) 


On all other forms, the default, LOC = BELOW is used. 


,LOC = (ANY,ANY) 




,LOC = RES 




,LOC = (RES,ANY) 




.RELATED = va/Me 


value: any valid macro keyword specification. 
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The parameters are explained as follows: 

LC,LA = length addr.A = addr 
LU,LA = length addr, A = addr 
VCjLA = length addr, A = addr 
VU,LA — length addr, A = addr 
EC^y = length value, A = addr 
EU,LV " length value, A — addr 
RCfLV = length value 
RUjLV = length value 
R,LV = length value 

VRC,LV = (maximum length value, minimum length value) 
VRU,LV — (maximum length value, minimum length value) 
specifies the type of GETMAIN request: 

LC and LU indicate conditional (LC) and unconditional (LU) list requests and specify 
requests for one or more areas of virtual storage. The length of each virtual storage area 
is indicated by the values in a list beginning at the address specified in the LA parameter. 
The address of each of the virtual storage areas is returned in a list beginning at the 
address specified in the A parameter. No virtual storage is allocated unless all of the 
requests in the list can be satisfied. 

VC and VU indicate conditional (VC) and unconditional (VU) variable requests and 
specify requests for single areas of virtual storage. The length of the single virtual storage 
area is between the two values at the address specified in the LA parameter. The address 
and actual length of the allocated virtual storage area are returned by the control program 
at the address indicated in the A parameter. 

EC and EU indicate conditional (EC) and unconditional (EU) element requests, and 
specify requests for single areas of virtual storage. The length of the single virtual storage 
area is indicated in the LV = length value parameter. The address of the allocated virtual 
storage area is returned at the address indicated in the A parameter. 

RC indicates a conditional register request, and R and RU indicate unconditional register 
requests. RC, RU, and R specify requests for single areas of virtual storage. The length 
of the single virtual area is indicated in the IN -length value parameter. The address of 
the allocated virtual storage area is returned in register 1. (R generates the SVC 10 
calling sequence, whereas RU and RC generate the SVC 120 and associated parameter 
format.) 

VRC and VRU indicate variable register conditional (VRC) and unconditional (VRU) 
requests for a single area of virtual storage. The length returned will be between ttie 
maximum and minimum lengths specified by the parameter IN — (maximum length value, 
minimum length value). The address of the allocated virtual storage is returned in register 
1 and the length in register 0. 



Notes: 



1. A conditional request indicates that the task is not to be abnormally terminated if virtual 
storage is not allocated to the active task. An unconditional request indicates that the 
task is to be abnormally terminated in this situation. 

2. The LC, LU, VC, VU, EC, EU, and R forms of the GETMAIN macro instruction can 
only be used to obtain virtual storage with addresses below 16 Mb. The RC, RU, VRC, 
and VRU forms of the GETMAIN macro instruction can be used to obtain virtual 
storage when the addresses are above 16 Mb or when the addresses are below 16Mb. 
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LA specifies the virtual storage address of consecutive fuUwords starting on a fullword 
boundary. Each fullword must contain the required length in the low-order three bytes, 
with the high-order byte set to 0. The lengths should be multiples of 8; if they are not, 
the control program uses the next higher multiple of 8. If VC or VU was coded, two 
words are required. The first word contains the minimum length required, the second 
word contains the maximum length. If LC or LU was coded, one word is required for 
each virtual storage area requested; the high-order bit of the last word must be set to 1 to 
indicate the end of the list. The list must not overlap the virtual storage area specified in 
the A parameter. 

LV = length value specifies the length, in bytes, of the requested virtual storage. The 
number should be a multiple of 8; if it is not, the control program uses the next higher 
multiple of 8. If R is specified, LV = (0) may be coded; the low-order three bytes of 
register 0 must contain the length, and the high-order byte must contain the subpool 
number, IN — {maximum length value, minimum length value) specifies the maximum and 
minimum values of the length of the storage request. 

A specifies the virtual storage address of consecutive fuUwords, starting on a fullword 
boundary. The control program places the address of the virtual storage area allocated in 
one or more words. If E was coded, one word is required. If L was coded, one word is 
required for each entry in the LA list. If V was coded, two words are required. The first 
word contains the address of the virtual storage area, and the second word contains the 
length actually allocated. The list must not overlap the virtual storage area specified in 
the LA parameter. 

,SP = subpool nmbr 

specifies the number of the subpool from which the virtual storage area is to be allocated. 
The subpool number must be a valid subpool number between 0 and 127. 

,BNDRY = DBLWD 
,BNDRY = PAGE 

specifies that alignment on a doubleword boundary (DBLWD) or alignment with the start 
of a virtual page on a 4K boundary (PAGE) is required for the start of a requested area. 
If one of the following subpools 226, 233-235, 239, 245, or 253-255 is requested, the 
fiNDRY = PAGE keyword is ignored. Requests for storage from these subpools are 
assigned from a single page, unless the request is greater than a page. 

,LOC= BELOW 
,LOC = (BELOW,ANY) 
,LOC = ANY 
,LOC = (ANY,ANY) 
,LOC = RES 
,LOC = (RES,ANY) 

specifies the location of virtual and real storage. When LOG is specified, real storage is 
allocated anywhere until the storage is fixed. After the storage is fixed, virtual and real 
storage are located in the following manner. 

LOG = BELOW indicates that real and virtual storage are to be located below 16 Mb. 

LOG = (BELOW, ANY) indicates that virtual storage is to be located below 16 Mb and 
real storage can be located anywhere. 

LOG = ANY and LOG = (ANY, ANY) indicates that virtual and real storage can be 
located anywhere. 
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Note: The LOC parameter is not valid for fixed subpools. For fixed subpools the actual 
location of the virtual storage area depends on the subpool specified. If the subpool is 
supported (backed) above 16 megabytes, GETMAIN attempts to locate the virtual 
storage area above 16 megabytes. If this is not possible, GETMAIN locates the virtual 
storage below 16 megabytes. LSQA subpools will be backed anywhere regardless of the 
LOC parameter. 

LOC = RES indicates that the location of virtual and real storage depends on the location 
of the caller. If the caller resides below 16 Mb, virtual and real storage are to be located 
below 16 Mb; if the caller resides above 16 Mb, virtual and real storage are to be located 
anywhere. 

LOC = (RES,ANY) indicates that the location of virtual storage depends upon the 
location of the caller. If the caller resides below 16 Mb, virtual storage is to be located 
below 16 Mb; if the caller resides above 16 Mb, virtual storage can be located anywhere. 
In either case, real storage can be located anywhere. 

,RELATED = va/Me 

specifies information used to self-document macro instructions by 'relating' functions or 
services to corresponding functions or services. The format and contents of the 
information specified are at the discretion of the user, and may be any valid coding 
values. 

The RELATED parameter is available on macro instructions that provide opposite 
services (for example, ATTACH/DETACH, GETMAIN/FREEMAIN, and 
LOAD/DELETE), and on macro instructions that relate to previous occurrences of the 
same macro instructions (for example, CHAP and ESTAE). 

The RELATED parameter may be used, for example, as follows: 

GETl GETMAIN R,LV=4096,RELATED=(FREE1, 

• GET STORAGE ' ) 



FREEl FREEMAIN R,LV=4096,A=( 1) ,RELATED=(GET1, 

• FREE STORAGE ' ) 

Note: Each of these macro instructions will fit on one line when coded, so there is no 
need for a continuation indicator. ) 

When control is returned, for conditional type requests (LC, ECj VC, RC, and VRC) register 
15 contains one of the following return codes: 

Hexadecimal 

Code Meaning 

00 Virtual storage requested was allocated. 

04 The request could not be satisfied because of insufficient virtual storage. 

The contents of registers 0, 1, and 15 are not preserved when the GETMAIN macro instruction 
is issued. 
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Example 1 



Operation: Obtain 400 bytes of storage from subpool 10. If the storage is available, the 
address will be returned in register 1 and register 15 will contain 0; if virtual storage is not 
available, register 15 will contain 4. 

GETMAIN RC,LV=400,SP=10 

Example 2 

Operation: Obtain 48 bytes of storage from default subpool 0. If the storage is available, the 
address will be stored in the word at AREAADDR; if the virtual storage is not available, the 

task will be abnormally terminated. 

GETMAIN EU,LV=48,A=AREAADDR 



AREAADDR DS F 

Example 3 

Operation: Obtain a maximum of 4096 or a minimum of 1024 bytes of virtual storage, with 
addresses above or below 16 Mb. Indicate that if the real storage is fixed, it should also be 
located above or below 16 Mb. If the storage is available, the address will be returned in 
register 1 and the length of the storage allocated will be returned in register 0; if the storage is 
not available, the task will be terminated. 

GETMAIN VRU,LV=( 4096, 1024) ,LOC=ANY 
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GETMAIN (List Form) 



Use the list form of the GETMAIN macro instruction to construct a control program 
parameter list. 

The list form of the GETMAIN macro instruction is written as follows: 



name 


name: symbol. Begin name in column L 




One or more blanks must precede GETMAIN. 








One or more blsnks must follow GETMAIN. 


LC 




LU 




VC 




VU 




EC 




EU 




,LA = length addr 


length addr: A-type address. 


,LV = length value 


length value: symbol or decimal digit. 




Note: LA may only be specified with EC or EU above. 




Note: LV may only be specified with LC, LU, or VU above. 


^=addr 


addr: A-type address. 


,SP =subpool nmbr 


subpool nmbr: symbol or decimal digit 0-127. 


,BNDRY=DBLWD 


Default: BNDRY=DBLWD 


,BNDRY = PAGE 




.RELATED = vc/Me 


value: any valid macro keyword specified. 


,MF = L 





The parameters are explained under the standard form of the GETMAIN macro instruction, 
with the following exception: 

,MF = L 

specifies the list form of the GETMAIN macro instruction. 
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GETMAE^ (Execute Form) 



A remote control program parameter list is used in, and can be modified by, the execute form 
of the GETMAIN macro instruction. The parameter list can be generated by the list form of 
either a GETMAIN or a FREEMAIN. 

The execute form of the GETMAIN macro instruction is written as follows: 



name name: symbol. Begin name in column 1. 

b One or more blanks must precede GETMAIN. 
GETMAIN 

b One or more blanks must follow GETMAIN. 



LC 
LU 
VC 
VU 
EC 
EU 

,LA = length addr 
,IN = length value 



,A=addr 

,SP = subpool nmbr 

,BNDRY = DBLWD 
,BNDRY = PAGE 

,RELATED = va/Me 

,MF = {E,crr/ prog) 



length addr: RX-type address or register (2) - (12). 
length value: symbol, decimal digit, or register (2) - (12). 
Note: LA may only be specified with EC or EU above. 
Note: LV may only be specified with LC, LU, VC, or VU above. 

addr: RX-type address, or register (2) - (12). 

subpool nmbr: symbol, decimal digit 0-127, or register (2) - (12). 

Default: BNDRY=DBLWD 

value: any valid macro keyword specified. 

Ctrl prog: RX-type address, or register (1) or (2) - (12). 



The parameters are explained under the standard form of the GETMAIN macro instruction, 
with the following exception: 

,MF = (E,cfr//)rog) 

specifies the execute form of the GETMAIN macro instruction using a remote control 
program parameter list. 
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IDENTIFY - Add an Entry Name 



The IDENTIFY macro instruction is used to add an entry name to a copy of a load module 
currently in virtual storage. The copy must be one of the following: 

• A copy that satisfied the requirements of a LOAD macro instruction issued during the 
execution of the current task. 

• The last load module given control, if control was passed to the load module using a 
LINK, ATTACH, or XCTL macro instruction. 

The IDENTIFY macro instruction may not be issued by an asynchronous exit routine. 
Normally, the IDENTIFY macro assigns the identified entry point as reentrant. A user issuing 
this macro should be sure that his program is reenterable, otherwise, results are unpredictable. 

An exception is the case of a non-authorized user identifying a module from an authorized 
library. In this case, the identified entry point is assigned the same attributes (reentrant, serially 
reusable, non-reusable, load only) as the main entry point. If the program is marked 
non-reusable, an ABEND 806 with a return code of four may result. The user should ensure 
that the program issuing this macro is reentrant or serially reusable if this exception applies. 

IDENTIFY services sets the addressing mode of the entry name that was added equal to the 
addressing mode of the major entry name. The system assigns the major entry name according 
to how the load module was constructed. 

• If the load module was constructed using the linkage editor (and brought into virtual 
storage via program fetch or virtual fetch), the major entry name is the name of the load 
module in the partitioned data set directory (not an aUas to that member). 

• If the load module was brought into storage by the loader, the major entry name is either 
the name that the user provided as input to the loader or the name that the loader used as 
a default. See the NAME = parameter in the LOADER section of Linkage Editor and 
Loader for information about how to specify this name. 

Note: You can override the addressing mode of the entry name by using the AMODE 
parameter in the FARM field of the EXEC JCL statement. 

If an authorized caller creates an entry name for a module in the pageable link pack area, 
IDENTIFY services places an entry for the alias on the active hnk pack area queue. If an 
unauthorized caller creates an entry name for a module in the pageable hnk pack area, 
IDENTIFY services places an entry for the alias on the task's job pack queue. 

The IDENTIFY macro instruction is written as follows: 



name 


name: symbol. Begin »ame in column 1. 




b 


One or more blanks must precede IDENTIFY. 




IDENTIFY 






b 


One or more blanks must follow IDENTIFY. 




EP — entry name 
EPL,OC = entry name addr 


entry name: symbol 

entry name addr: RX-type address, or register (0) or (2) - 


(12). 


,ENTRY = enfry addr added 


entry addr added: RX-type address, or register (1) or (2) 


- (12). 
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The parameters are explained as follows: 

EP = entry name 

EPLOC = entry name addr 

specifies the entry name or address of the entry name. The name does not have to 
correspond to any symbol or name in the load module, and must not correspond to any 
name, alias, or added entry name for a load module in the link pack area queue, or the 
job pack area of the job step. If EPLOC is coded, the name must be padded to eight 
bytes, if necessary. 

,ENTRY = entry addr added 

specifies the virtual storage address of the entry point being added. 

When control is returned, register 15 contains one of the following return codes: 

Hexadecimal 

Code Meaning 

00 Successful completion of requested function. 

04 Entry name and address already exist. 

08 Entry name duplicates the name of a load module currently in virtual storage; entry address was not 

added. 

OC Entry address is not within an eligible load module; entry address was not added. 

10 Request issued by an asynchronous exit routine; entry address was not added. 

14 LINK, LOAD, XCTL, ATTACH, or IDENTIFY request was previously issued using the same entry 

name but a different address; current request was ignored. 

18 Parameter list is invalid or is not on a word boundary. 

IC Extent list length is not positive or a multiple of 8, or extent address is not on a double word boundary, 

is not addressable, or is not in caller's region. 

24 Unexpected system error. 

28 EPLOC address is fetch protected. 

Example 1 

Operation: Add an entry name (PGMTAL2A) to a load module in virtual storage. Register 3 
contains the entry point address. 

IDENTIFY EP=PGMTAL2A,ENTRY=(R3) 
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LINK — Pass Control to a Program in Another Load Module 



If your program is to execute in 31 -bit addressing mode, you must use the MVS/XA version of 
this macro instruction. 

The LINK macro instruction is used to pass control to a specified entry name in another load 
module; the entry name must be a member name or an alias in a directory of a partitioned data 
set (PDS) or must have been specified in an IDENTIFY macro instruction. The load module 
containing the program is brought into virtual storage if a usable copy is not available. 

LINK processing handles the setting of the addressing mode when passing control. The called 
program is given control in the addressing mode indicated in its PDS directory entry. On entry 
to the called program, the high-order bit, bit 0, of register 14 is set to indicate the addressing 
mode of the issuer of the LINK macro. If bit 0 is 0, the issuer is executing in 24-bit addressing 
mode; if bit 0 is 1, the issuer is executing in 31 -bit addressing mode. This makes it possible to 
return control to the calling program in the addressing mode in which it was executing. 

The problem program optionally can provide a parameter list to be passed to the called 
program. If the called program terminates abnormally, or if the specified entry point cannot be 
located, the task is abnormally terminated. 

The standard form of the LINK macro instruction is written as follows: 



name 


name: symbol. Begin «ame in column 1 . 


b 


One or more blanks must precede LINK. 


LINK 




b 


One or more blanks must follow LINK. 


EP = entry name 
EPLOC = entry name addr 
DE = list entry addr 


entry name: symbol 

entry name addr: A-type address, or register (2) - (12). 
list entry addr: A-type address, or register (2) - (12). 


,DCB = deb addr 


deb addr: A-type address, or register (2) - (12). 


,PARAM = (addr) 
,PARAM = (addr),YL = 1 


addr: A-type address, or register (2) - (12). 

Note: addr is one or more addresses, separated by commas. For example, 
{addr, addr, addr) 


,ID = id nmbr 


id nmbr: symbol or decimal digit, with a maximum value of 4095. 


jERRET = err rtn addr 


err rtn addr: A-type address, or register (2) - (12). 


,LSEARCH = NO 
,LSEARCH = YES 


Default: No 



The parameters are explained as follows: 

EP = entry name 
EPLOC = entry name addr 
DE = list entry addr 

specifies the entry name, the address of the entry name, or the address of the name field 
in a 60-byte list entry for the entry name that was constructed using the BLDL macro 
instruction. If EPLOC is coded, the name must be padded to eight bytes, if necessary. If 
an unauthorized program issues the LINK macro instruction and the DE parameter 
specifies an entry in an authorized Ubrary, the program-supplied DE information is 
ignored for integrity reasons. Instead, contents management uses the BLDL macro 
instruction to construct a new list entry containing the DE information for the LINK. 
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Note: The task structure must not be changed via an ATTACH or DETACH between 
the issuance of the BLDL and the issuance of the ATTACH for the module, or an abend 
106 with a return code of 15 might result. The DE information supplied by an 
unauthorized program will also be ignored if the LINK macro instruction is requesting 
access to a program or library that is controlled by the System Authorization Facility. 

,Y)CB = dcb addr 

specifies the address of the opened data control block for the partitioned data set 
containing the entry name described above. This parameter must indicate the same DCB 
used in the BLDL mentioned above. 

If the DCB parameter is omitted or if DCB = 0 is specified when the LINK macro 
instruction is issued by the job step task, the data sets referred to by either the STEPLIB 
or JOBLIB DD statement are first searched for the entry point name. If the entry point 
name is not found, the Unk library is searched. 

If the DCB parameter is omitted or if DCB = 0 is specified when the LINK macro 
instruction is issued by a sub task, the data sets associated with one or more data control 
blocks referred to by the TASKLIB operand of previous ATTACH macro instructions in 
the subtasking chain are first searched for the entry point name. If the entry point name 
is not found, the search is continued as if LINK had been issued by the job step task. 

Note: DCB must reside in 24-bit addressable storage. 

,PARAM = Mi/r) 

,PARAM = {addr^WJ. - 1 

specifies address(es) to be passed to the called program. Each address is expanded inline 
to a fuUword on a fuUword boundary, in the order designated. Register 1 contains the 
address of the first parameter when the program is given control. (If this parameter is not 
coded, register 1 is not altered unless the execute form of the LINK macro instruction is 
coded.) 

VL = 1 should be designated only if the called program can be passed a variable number 
of parameters. VL= 1 causes the high-order bit of the last address parameter to be set to 
1; the bit can be checked to find the end of the Ust. 

,ID = id nmbr 

specifies an identifier useful for debugging purposes only. The last fuUword of the macro 
expansion is a NOP instruction containing the identifier value in bytes 3 and 4. 

= err rtn addr 

specifies the address of a routine to receive control when an error condition that would 
cause an abnormal termination of the task is detected. Register 1 contains the abend 
code that would have resulted had the task abended. The routine does not receive control 
when input parameter errors are detected. 

,LSEARCH = NO 
,LSEARCH = ,YES 

specifies whether (YES) or not (NO) the search is to be Umited to the job pack area and 
the first library in the normal search sequence. 
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Example 1 

Operation: Pass control to a specified entry name (PGMLKRUS) in another load module. Let 
the system find the module fi-om available libraries. 

LINK EP=PGMLKRUS 

Example 2 

Operation: Pass control to a specified entry name (PGMA) in another load module, specifying 
(in registers 4, 6, 8) three addresses to be passed to the called program. 

LINK EP=PGMA,PARAM=( (4) , (6) , (8) ) 
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LINK (List Form) 



Two parameter lists are used in a LINK macro instruction: a control program parameter list 
and problem program parameter list. Only the control program parameter list can be 
constructed in the Ust form of LINK. Address parameters to be passed in a parameter list to 
the problem program can be provided using the list form of CALL. This parameter list can be 
referred to in the execute form of LINK. 

The list form of the LINK macro instruction is written as follows: 



luane name: symbol. Begin name in column 1. 

b One or more blanks must precede LINK. 
LINK 

b One or more blanks must follow LINK. 



EP — entry name 
EPLOC = e«f/y name addr 
DE = list entry addr 

,DCB = deb addr 

,ERRET = err rtn addr 

,LSEARCH = NO 
,LSEARCH=YES 

,SF = L 



entry name: symbol 

entry name addr: A-type address. 

list entry addr: A-type address. 

deb addr: A-type address. 

err rtn addr: A-type address. 

Default: No 



The parameters are explained under the standard form of the LINK macro instruction, with the 
following exception: 

,SF = L 

specifies the list form of the LINK macro instruction. 
Notes: 

1. Coding the LSEARCH parameter causes a parameter list to be created that is different from 
the list created when LSEARCH is omitted. If you code LSEARCH in either the list or 
execute form of the macro instruction, you must code it in both forms. 

2. If ERRET is coded in the list form and not specified in the execute form, the error routine 
specified in the list form will be retained and used in the execute form of the macro 
instruction. If ERRET is specified in both the list and the execute form, the error routine 
specified in the execute form of the macro instruction will be used. 
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LINK (Execute Form) 



Two parameter lists are used in a LINK macro instruction: a control program parameter list 
and an optional problem program parameter list. Either or both of these lists can be remote 
and can be referred to and modified by the execute form of LINK. If only one of the 
parameter lists is remote, parameters that require use of the other parameter list cause that list 
to be constructed inUne as part of the macro expansion. 

The execute form of the LINK macro instruction is written as follows: 



name: symbol. Begin name in columD 1 . 
One or more blanks must precede LINK. 

One or more blanks must follow LINK. 



name 

b 

LINK 
b 



EP = entry name 
EPLOC = entry name addr 
DE = list entry addr 

J>CB = deb addr 

,P\RAM = (addr) 
,PARAM = iaddr),YL = 1 

,ID = id nmhr 

,ERRET = err rtn addr 

,LSEARCH = NO 
,LSEARCH = YES 

,MF = (E,/?ro* addr) 
,SF = (E,ctrl addr) 

,MF = (E^ro6 addr),S¥ = (E,etrl addr) 



entry name: symbol. 

entry name addr: RX-type address or register (2) - (12). 
list entry addr: RX-type address, or register (2) - (12). 

deb addr: RX-type address, or register (2) - (12). 

addr: RX-type address, or register (2) - (12). 

Note: addr is one or more addresses, separated by commas. For example, 
(addr, addr, addr) 

id nmbr: symbol or decimal digit, with a maximum value of 4095. 
err rtn addr: RX-type address or register (2) - (12). 
Default: No 

prob addr: RX-type address, or register (1) or (2) - (12). 
Ctrl addr: RX-type address, or register (2) - (12) or (1^. 



The parameters are explained under the standard form of the LINK macro instruction, with the 
following exceptions: 

,MF = (E^ro6 addr) 
,SF =(k,ctrl addr) 

,MF = (E,prob addr),SF = (E.ctrl addr) 

specifies the execute form of the LINK macro instruction. This form uses a remote 
problem program parameter list, a remote control program parameter Ust, or both. 

Notes: 

1. Coding the LSEARCH parameter causes a parameter list to be created that is different from 
the list created when LSEARCH is omitted. If you code LSEARCH in either the list or the 
execute form of the macro instruction, you must code it in both forms. 

2. If ERRET is coded in the list form and not specified in the execute form, the error routine 
specified in the list form will be retained and used in the execute form of the macro 
instruction. If ERRET is specified in both the list and the execute form, the error routine 
specified in the execute form of the macro instruction will be used. 
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LOAD — Bring a Load Module into Virtual Storage 



The LOAD macro instruction is used to bring the load module containing the specified entry 
name into virtual storage, if a usable copy is not available in virtual storage. 

LOAD services places the load module in storage above or below the 16 megabyte line 
depending on the module's RMODE, which is specified in the partitioned data set's directory 
entry for the module. 

The responsibility count for the load module is increased by one. On output, the high-order 
byte of register 1 contains the authorization code of the loaded module and the low three bytes 
contain the module's length in doubleworda. Control is not passed to the load module; instead, 
the virtual storage address of the designated entry point is returned in register 0. The load 
module remains in virtual storage until the responsibiUty count is reduced to 0 through task 
terminations or until the effects of all outstanding LOAD requests for the module have been 
canceled (using the DELETE macro instruction), and there is no other requirement for the 
module. 

LOAD services sets the high order bit of the entry point address in register 0 to indicate the 
module's AMODE, which is obtained from the partitioned data set's directory entry for the 
module. If the module's AMODE is 31, it sets the indicator to 1; if the module's AMODE is 
24, it sets the indicator to 0; and if the module's AMODE is ANY, it sets the indicator to 
correspond to the caller's AMODE. 

The entry name in the load module must be a member name or an alias in a directory of a 
partitioned data set or must have been specified in the IDENTIFY macro instruction. If the 
entry name was previously specified in an IDENTIFY macro instruction, no attempt is made to 
bring in an additional copy of the module. If the specified entry name cannot be located, the 
task is abnormally terminated. 

The LOAD macro instruction is written as follows: 



name 


name: symbol. Begin name in column 1 . 


b 


One or more blanks must precede LOAD. 


LOAD 




b 


One or more blanks must follow LOAD. 


EP^ entry name 
EPLOC = entry name addr 

DE = list entry addr 


entry name: symbol. 

entry name addr: If LSEARCH or LOADPT is specified, A-type address or 
register (2) - (12); otherwise, RX-type address or register (0) or (2) - (12). 
list entry addr: If LSEARCH or LOADPT is specified, A-type address or 
register (2) - (12); otherwise, RX-type address, or register (2) - (12). 


,T>CB = deb addr 


deb addr: If LSEARCH or LOADPT is specified, A-type address or register 
(2) - (12); otherwise, RX-type address, or register (1) or (2) - (12). 


,ERRET= err rtn addr 


err rtn addr: RX-type address or register (2) - (12). 


,LSEARCH = NO 
,LSEARCH = YES 


Default: No 


XOADfT = addr 


addr: A-type address or register (2) - (12). 


.RELATED = va/tie 


valtie: any valid macro keyword specification. 



LOAD- 
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The parameters are explained as follows: 

EP = entry name 
EPLOC = entry name addr 
T3iE = list entry addr 

specifies the entry name, the address of the name, or the address of the name field in a 
60-byte Ust entry for the entry name that was constructed using the BLDL macro 
instruction. If EPLOC is coded, the name must be padded to eight bytes, if necessary. 

If an unauthorized program issues the LOAD macro instruction and the DE parameter 
specifies an entry in an authorized library, the program-supplied DE information is 
ignored for integrity reasons. Instead, contents management uses the BLDL macro 
instruction to construct a new hst entry containing the DE information for the LOAD. 
The DE information supplied by an unauthorized program will also be ignored if the 
LOAD macro instruction is requesting access to a program or library that is controlled by 
the System Authorization Facility. 

Note: The task structure must not be changed via an ATTACH or DETACH between 
the issuance of the BLDL and the issuance of the ATTACH for the module, or an abend 
106 with a return code of 15 might result. 

,DCB=' deb addr 

specifies the address of the opened data control block for the partitioned data set 
containing the entry name described above. This parameter must indicate the same DCB 
used in the BLDL mentioned above. 

If the DCB parameter is omitted or if DCB = 0 is specified when the LOAD macro 
instruction is issued by the job step task, the data sets referred to by either the STEPLIB 
or JOBLIB DD statement are first searched for the entry name. If the entry name is not 
found, the Unk library is searched. 

If the DCB parameter is omitted or if DCB =0 is specified when the LOAD macro 
instruction is issued by a subtask, the data sets associated with one or more data control 
blocks referred to by the TASKLIB operand of previous ATTACH macro instructions in 
the subtasking chain are first searched for the entry name. If the entry name is not found, 
the search is continued as if the LOAD had been issued by the job step task. 

Note: DCB must reside in 24-bit addressable storage. 

,ERRET = err rtn addr 

specifies the address of a routine to receive control when an error condition that would 
cause an abnormal termination of the task is detected. Register 1 contains the abend 
code that would have resulted had the task abended, and register 15 contains the reason 
code that is associated with the abend. The routine does not receive control when input 
parameter errors are detected. 

,LSEARCH = NO 
J.SEARCH = YES 

specifies whether (YES) or not (NO) the search is to be limited to the job pack area and 
the first library in the normal search sequence. 

,LOAD¥T = addr 

specifies that the starting address at which the module was loaded is to be returned to the 
caller at the indicated address. 
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,RELATED = va/Me 

specifies information used to self-document macro instructions by 'relating' functions or 
services to corresponding functions or services. The format and contents of the 
information specified are at the discretion of the user, and may be any valid coding 
values. 

The RELATED parameter is available on macro instructions that provide opposite 
services (for example, ATTACH/DETACH, GETMAIN/FREEMAIN, and 
LOAD /DELETE), and on macro instructions that relate to previous occurrences of the 
same macro instructions (for example, CHAP and ESTAE). 

The RELATED parameter may be used, for example, as follows: 

LOADl LOAD EP=APGI0HK1 , RELATED= ( DELI , 

• LOAD APGIOHKl ' ) 



DELI DELETE EP=APGI0HK1,RELATED=( LOADl, 

' DELETE APGIOHKl ' ) 

Note: Each of these macro instructions will fit on one line when coded, so there is no 
need for a continuation indicator. 

Example 1 

Operation: Bring a load module containing a specified entry name (PGMLKRUS) into virtual 
storage. Let the system find the module from available libraries. 

LOAD EP=PGMLKRUS 

Example 2 

Operation: Bring a load module containing the entry name EPNAME into virtual storage. 
Indicate that register 7 contains the address of the DCB associated with the partitioned data set 
that contains this load module. Return the load address of the requested module in the 
location pointed to by register 8. If an error occurs during this processing, transfer control to 
the error routine located at ERRADDR. 

LOAD EP=EPNAME , DCB= ( 7 ) , LOADPT= ( 8 ) , ERRET=ERRADDR 
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LOAD (List Form) 



The list form of the LOAD macro instruction builds a non-executable problem program 
parameter list that can be referred to or modified by the execute form of the LOAD macro 
instruction. 

The Ust form of the LOAD macro instruction is written as follows: 



name 

b 

LOAD 

b 


name: symbol. Begin name in column 1. 
One or more blanks must precede LOAD. 

One or more blanks must follow LOAD. 


'E^= entry name 


entry nrnie: symbol. 


EPLOC = entry name addr 


entry name addr: A-type address. 


DE = list entry addr 


list entry addr: A-type address. 


,I>Cli= deb addr 


deb addr: A-type address. 


,LSEARCH = NO 


Default: No 


,LSEARCH = YES 




,LOADPT=arfdlr 


addr: A-type address. 


,RELATED = vo/tte 


value: any valid macro keyword specification. 


,SF = L 





The parameters are explained under the standard form of the LOAD macro instruction with the 
following exception: 

,SF=L 

specifies the Ust form of the LOAD macro instruction. 
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LOAD (Execute Form) 



The execute form of the LOAD macro instruction can refer to and modify the parameter list 
constructed by the list form of the macro instruction. 

The execute form of the LOAD macro instruction is written as follows: 



name 


name: symbol. Begin name in column 1. 


b 


One or more blanks must precede LOAD. 


LOAD 




b 


One or more blanks must follow LOAD. 


EF = entry name 

EPLOC = entry name addr 

DE = list entry addr 


entry name: symbol. 

entry name addr: RX-type address, or register (2) - (12). 
list entry addr: RX-type address, or register (2) - (12). 


,DCB = deb addr 


deb addr: RX-type address, or register (2) - (12). 


,ERRET = err rtn addr 


err rtn addr: RX-type address, or register (2) - (12). 


,LSEARCH = NO 
,LSEARCH = YES 


Default: No 


,LOADPT =a</rfr 


addr: RX-type address or register (2) - (12). 


.RELATED = va/Me 


value: any valid macro keyword specification. 


,S¥=(E,listaddf) 


list addr: RX-type address or register (2) - (12) or (15). 



The parameters are explained under the standard form of the LOAD macro instruction with the 
following exception: 

,SF = (E,/wi addr) 

specifies the execute form of the LOAD macro instruction. 
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PGLOAD — Load Virtual Storage Areas into Real Storage 



The PGLOAD macro instruction is used to load specified virtual storage areas into real storage 
in anticipation of future needs. That is, PGLOAD is essentially a page-ahead function. The 
PGLOAD macro instruction performs this function for virtual addresses below 16 Mb; the 
LOAD option of the PGSER macro instruction performs the same function for virtual 
addresses either above or below 16 Mb. Note, however, that a page that has been loaded via 
PGLOAD is ehgible for page-out selection in the same manner as a page that has been 
demand-paged into real storage. 

The misuse of this function can have adverse effects on system performance. Causing 
unnecessary pages to be brought into real storage will force more useful pages to be displaced 
and, consequently, cause unnecessary paging activity. Proper use of this function, however, will 
tend to decrease system overhead resulting from page faults. 

The standard form of the PGLOAD macro instruction is written as follows: 





name 


name: symbol. Begin in column 1 . 


b 




One or more blanks must precede PGLOAD. 


PGLOAD 




b 




One or more blanks must follow PGLOAD. 


R 

,A = 


start addr 


start addr: A-type address, or register (1) or (2) - (12). 




,ECB = ecb addr 


ecb addr: A-type address, or register (0) or (2) - (12). 




,EA = end addr 


end addr: A-type address, or register (2) - (12) or (15). 
Default: start addr + 1 




,RELEASE = N 
.RELEASE = Y 


Default: RELEASE = N 

Note: RELEASE = Y may only be specified with EA above. 



The parameters are explained as follows: 
R 

specifies that no parameter list is being supplied with this request. 
,A = start addr 

specifies the start address of the virtual area to be loaded. 
,ECB = ecb addr 

specifies the address of an ECB that is used to signal event completion. 
,EA = end addr 

specifies the end address + 1 of the virtual area to be loaded. 

,RELEASE = N 
,RELEASE = Y 

specifies that the contents of the virtual area is to remain intact (N) or be released (Y). 
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When control is returned, register 15 contains one of the following return codes: 



Hexadecimal 
Code 



Meanii^ 

Operation completed normally; ECB posted complete. 

Operation proceeding; ECB will be posted when all page-ins are complete. 



00 
08 



Example 1 



Example 2 



Example 3 



If control is not returned, an ABEND is issued with the following reason codes in register 15: 

Hexadecimal 



If the ECB parameter is coded, the ECB is unchanged if the request was initiated but not 
complete (return code 8), or if an ABEND was issued with return code 10. Otherwise, the ECB 
is posted complete with code 

0 - Operation completed successfully. 

If the return code issued is 8, the ECB is posted asynchronously when paging I/O has 
completed, with code 

0 - Operation completed successfully. 



Operation: Page-in a single byte of virtual storage, causing the entire 4096-byte page 
containing that byte to be paged into real storage. 

PGLOAD R,A=(R3) 

Operation: Page-in the virtual storage lying in the range addressed by registers 3 and 4, and 
notify the requestor via posting of the ECB when the page-ins are complete. 

PGLOAD R,A=(R3) ,EA=(R4) ,ECB=(R5) 

Operation: Discard the contents of the virtual pages totally encompassed by START AD and 
ENDAD before new real storage frames are assigned. 

PGLOAD R , A=STANDARD , EA=ENDAD , RELEASE=Y 



Code 



Meaning 



10 



Virtual subarea list entry or ECB address invalid. No ECB is posted. 
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PGLOAD (List Fonn) 



The list form of the PGLOAD macro instructioti uses a virtual subarea list. 
The list form of the PGLOAD macro instruction is written as follows: 



name 


ruane: symbol. Begin name in column 1. 


b 


One or more blanks must precede PGLOAD. 


PGLOAD 




b 


One or more blanks must follow PGLOAD. 


L 

,LA = list addr 


list addr: A-type address, or register (1) or (2) - (12). 


,ECB = ecb addr 


ecbaddr: A-type address, or register (0) - (2) or (15). 


,RELEASE=N 


Default: RELEASE =N 


.RELEASE =Y 





The parameters are explained under the standard form of the PGLOAD macro instruction, with 
the following exceptions: 

L 

specifies that a parameter list is being supplied with this request. 
,LA — list addr 

specifies the address of the first entry of a virtual subarea list. 
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PGOUT — Page Out Virtual Storage Areas from Real Storage 



The PGOUT macro instruction is used to initiate page-out operations for specified virtual 
storage areas that are in real storage. The PGOUT macro instruction performs this function 
for virtual addresses below 16 Mb; the OUT option of the PGSER macro instruction performs 
the same function for virtual addresses either above or below 16 Mb. The PGOUT function is 
complementary to the PGLOAD function. You have the option of specifying that the virtual 
pages to be paged out either remain valid in real storage or be marked invalid and the real 
frames assigned to them be made available for reuse. The use of this option will not prevent 
page faults from occurring on the specified storage. 

The misuse of this function, like the misuse of the PGLOAD fimction, can have adverse effects 
on system performance. On the other hand, proper use of this function will tend to clean out 
of real storage those pages no longer needed for program execution or not required for some 
period in the future. 

The standard form of the PGOUT macro instruction is written as follows: 



name 

h 

PGOUT 
b 


name: symbol. Begin name in column 1 . 
One or more blanks must precede PGOUT. 

One or more blanks must follow PGOUT. 


R 




,A= start addr 


start addr: A-type address, or register (1) or (2) - (12). 


,EA = end addr 


end addr: A-type address, or register (2) - (12) or (15). 


,KEEPREL = N 


Default: KEEPREL = N 


,KEEPREL = Y 





The parameters are explained as follows: 
R 

specifies that no parameter list is being supplied with this request. 
start addr 

specifies the start address of the virtual area to be paged out. 
,EA = end addr 

specifies the end address + 1 of the virtual area to be paged out. 

,KEEPREL = N 
,KEEPREL = Y 

specifies that the virtual pages will be marked invalid and the real storage frames freed for 
reuse (N) or that the virtual pages will not be invalidated (Y). 
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When control is returned, register 15 contains one of the following return codes: 



Hexadedmal 
Code 



Meanii^ 



00 



Operation completed normally; paging I/O proceeding asynchronously. 



OC 



One or more pages specified to be paged out were not paged out. Either the pages were in the nucleus 
in unusable real frames, in SQA or LSQA, in V = R area allocated region, were page fixed, or the system 
resoxirces necessary to perform the page out operations were momentarily unavailable. Paging I/O is 
proceeding normally for all other pages. 



10 



Operation abnormally terminated. Virtual subarea list entry invalid. 



Example 1 



Example 2 



Operation: Page-out the area of real storage totally encompassed by the start and end virtual 
boundaries specified. 

PGOUT R,A=(R3) ,EA=(R4) 

Operation: Create an auxiliary storage copy of a virtual area before continuing to use the area. 
The area will remain in real storage after the page-outs complete. 

PGOUT R , A= ( R3 ) , EA= ( R4 ) , KEEPREL=Y 
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PGOUT (List Form) 



The list form of the PGOUT macro instruction uses a virtual subarea list. 
The list form of the PGOUT macro instruction is written as follows: 



name name: symbol. Begin name in column 1. 

b One or more blanks must precede PGOUT. 
PGOUT 

b One or more blanks must follow PGOUT. 
L 

,LA = /w/ addr list addr: A-type address, or register (1) or (2) - (12). 

,KEEPREL = N Default: KEEPREL = N 
,KEEPREL = Y 



The parameters are explained under the standard form of the PGOUT macro instruction, with 
the following exceptions: 

L 

specifies that a parameter list is being supplied with this request. 
,luA — list addr 

specifies the address of the first entry of a virtual subarea Ust (VSL). See the topic 
"Virtual Subarea List (VSL)" in Part I for a description of the VSL. 
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PGRLSE — Release Virtual Storage Contents 



The PGRLSE macro instruction is used to release to the system all real storage and auxiliary 
storage associated with specified pageable virtual storage areas. The PGRLSE macro 
instruction performs this function for virtual addresses below 16 Mb; the RELEASE option of 
the PGSER macro instruction performs the same function for virtual addresses either above or 
below 16 Mb. Use PGRLSE when a large area (one or more complete pages) of virtual storage 
within your program no longer has significant contents. 

Functionally, PGRLSE is equivalent to a FREEMAIN macro instruction followed by a 
GETMAIN macro instruction. That is, the virtual space is maintained, but the data is 
discarded. When the page(s) being released is next referred to, that page is cleared to zeros. 
Thus, you can help reduce system overhead by releasing virtual storage when you no longer 
need it. 

Proper use of this function can increase the amount of storage available to the system and 
prevent needless paging I/O activity. Usage of PGRLSE may improve operating efficiency 
when the using program can discard the contents of a large virtual storage area and reuse the 
virtual storage pages; paging operations may be eliminated for those virtual storage pages when 
they are reused. 

The standard form of the PGRLSE macro instruction is written as follows: 



name 


name: symbol. Begin name in column 1 . 




b 


One or more blanks must precede PGRLSE. 




PGRLSE 






b 


One or more blanks must follow PGRLSE. 




LA = low addr 


low addr: A-type address, or register (0) or (2) - 


(12). 


,nA=high addr 


high addr: A-type address, or register (1) or (2) 


- (12). 



The parameters are explained as follows: 
LA = low addr 

specifies the address of the lower boundary of the area to be released. 
,HA = high addr 

specifies the address of the upper boundary + 1 of the area to be released. 

Wlien control is returned, register 15 contains one of the following return codes: 
Hexadecimal 



Code Meaning 

00 Successful completion. 

04 Execution failed. The area specified, or a portion of the area, is protected from the requesting program.- 

Any valid portion of the area preceding the protected area is released. 
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Example 1 

Operation: Release the contents of the pages included within the specified areas. Only those 
pages fully encompassed will be nullified. 

PGRLSE LA= ( R4 ) , HA= ( R5 ) 

Example 2 

Operation: Perform the operation in Example 1, but use A-type addresses. 

PGRLSE LA=LOWADDR,HA=HIGHADDR 
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PGRLSE (List Form) 



The list form of the PGRLSE macro instruction is used to construct a control program 
parameter list. 

The list form of the PGRLSE macro instruction is written as follows: 



name name: symbol. Begin name in column 1. 

b One or more blanks must precede PGRLSE. 
PGRLSE 

b One or more blanks must follow PGRLSE. 



LA = low addr, low addr: A-type address. 

HA^ high addr, high addr: A-type address. 

MF = L 



The parameters are explained under the standard form of the PGRLSE macro instruction, with 
the following exception: 

MF=L 

specifies the list form of the PGRLSE macro instruction. 
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PGKLSE (Execute Fom) 



A remote control program parameter list is referred to, and can be modified by, the execute 
form of the PGRLSE macro instruction. 

The execute form of the PGRLSE macro instruction is written as follows: 



name 


name: symbol. Begin name in column \. 


h 


One or more blanks must precede PGRLSE. 


PGRLSE 




b 


One or more blanks must follow PGRLSE. 


LA = low addr. 


low addr: A-type address, or register (0) or (2) - (12). 


liA= high addr. 


high addr: A-type address, or register (1) or (2) - (12). 


MF-(E,ctrladdr) 


Ctrl addr: RX-type address, or register (2) - (12). 



The parameters are explained under the standard form of the PGRLSE macro instruction, with 
the following exception: 

MF = (E,cfr/ addr) 

specifies the execute form of the PGRLSE macro instruction using a remote control 
program parameter Ust. 
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PGSER - Page Services 



The PGSER macro instruction performs the same paging services as PGLOAD, PGOUT, and 
PGRLSE. PGSER performs these services for addresses either above or below 16 Mb. 

The services are: 

• Page load equivalent to PGLOAD 

• Page out equivalent to PGOUT 

• Page release equivalent to PGRLSE 

If the common area is being released and the caller is not in key zero, the caller's key must 
match the key of the storage. 

Regardless of the addressing mode, all addresses passed in registers are used as 31 -bit addresses. 
All RX-type addresses are assumed to be in the addressing mode of the caller. The standard 
form of the PGSER macro instruction is written as follows: 



name 


name: symbol. Begin name in column 1. 


b 


One or more blanks must precede PGSER. 


PGSER 




b 


One or more blanks must follow PGSER. 


R 
L 

,LOAD 
,OUT 

.RELEASE 




,LA = list addr 


list addr: RX-type address or register (1), (2) - (12). 
Note: This parameter is valid only with L. 


^= start addr 


start addr: RX-type address or register (1), (2) - (12). 
Note: This parameter is valid only with R. 


,EA= end addr 


Default: EA= start addr 

end addr: RX-type address or register (15), (2) - (12). 
Note: This parameter is valid only with R. 


,ECB = ecb addr 


Default: If LOAD is specified, ECB = 0. 

ecb addr: RX-type address or register (0) or (2) - (12). 

Note: This parameter is optional if LOAD is specified and is invalid for OUT 
and RELEASE. 


.RELEASE = Y 
.RELEASE =N 


Default: RELEASE = N 

Note: This parameter may be specified only if LOAD is specified. 


,KEEPREL = Y 
,KEEPREL = N 


Default: KEEPREL = N 

Note: This parameter may be specified only if OUT is spedfied. 


.RELATED = va/Me 


value: any valid macro keyword specification. 
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R 

L 

specifies the manner in which the input is supplied. If R is specified, the user supplies the 
starting and ending addresses of the virtual area for which the service needs to be 
performed. Before processing the request, page services puts these addresses in registers 1 
and 15, respectively. If L is specified, the user suppUes the address of the page services 
list (PSL), which specifies the virtual area for which the service is to be performed. Before 
processing the request, page services puts the address of the PSL in register 1. See the 
topic "Page Service List (PSL)" in Part I for a description of the PSL. 



,LOAD 

,OUT 

^RELEASE 

indicates the function to be performed. 



LOAD specifies that a page-in operation is to be initiated for the virtual storage area 
specified, in anticipation of future needs. 

OUT specifies that a page-out operation is to be initiated for the virtual storage area 
specified. 

RELEASE specifies that all real and auxiliary storage, associated with the virtual storage 
area specified, is to be released. 

,LA • list addr 

specifies the address of the page services list O^SL) for L requests. 
th — start addr 

specifies the address of the start of the virtual area for R requests. 
,EA=eni/ addr 

specifies the address of the end of the virtual area for R requests. 
Note: PGLOAD, PGOUT, and PGRLSE use end + 1 as the value for the end address. 
,ECB=ecb addr 

specifies the address of the ECB that is used to signal event completion for a LOAD 
request. 

If an ECB is supplied, the caller must check the return code because the ECB will not be 
posted if the return code is zero. If an ECB is not supplied, it is not necessary to check 
the return code because control returns to the caller oh\y if the request was suc(%ssfully 
completed; if unsuccessful, page services abnormally terminates the caller. 

Page services verifies that the ECB address is in an area allocated via GETMAIN and 
that the ECB is in the caller's protect key. Before posting the ECB, page services again 
verifies that the ECB is located in an allocated area and that the ECB is in the caller's 
protect key. (This is to check that the allocated area has not been freed via FREEMAIN 
and the protect key has not been changed.) It is the user's responsibiUty to ensure that 
the page containing the ECB is not freed and that the key is not altered. If either test 
fails, page services does not post the ECB. 
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,RELEASE = Y 
,RELEASE=N 

specifies that all the real and auxiliary storage associated with the virtual storage areas is 
to be released to the system (Y) or that all the real and auxiliary storage associated with 
the virtual storage areas is not to be released to the system (N). 

,KEEPREL=Y 
,KEEPREL=N 

specifies that the virtual pages should be validated again after the page-out completes (Y); 
or that the virtual pages will be marked invalid and the real storage frames freed for reuse 
(N). 

,RELATED = vfl/Me 

provides information to dociraient the macro by relating the service performed to some 
corresponding function or service. The format can be any valid coding value that the user 
chooses. 

On return the register contents are as follows: 
Register Contents 

0-4 The contents are destroyed and unpredictable. 

5-13 The contents are unchanged. 

14 The contents are destroyed and unpredictable. 

15 This register contains the return code. 



The return codes, given in register 15, along with the option used and the meaning follow: 



Option 


Code 


Meaning 


LOAD 


0 


The operation completed normally and the ECB will not be posted. If no ECB is supplied, the 
operation is completed or proceeding. 


LOAD 


8 


The operation is proceeding. The ECB, if applicable and available, will be posted with X'OO' when 
all page-ins are complete. 


OUT 


0 


The operation completed normally. 


OUT 


C 


One or more pages specified to be paged-out was not paged out. The page service is proceeding 

for the other pages 


RELEASE 


0 


The operation completed normally. 



If an error is found in one of the parameters, the requestor is abnormally terminated with a 
system abend code of X'18A' and one of the following hexadecimal reason codes is provided in 
register 15: 

Hexadedmal 



Code Meanii^ 

4 A page-release operation abnormally terminated because either a page release was attempted for 

permanently backed storage or a non-system key caller attempted to release storage in a different key. 

10 A page-load operation abnormally terminated because the PSL or ECB address was invalid. (An ECB 

can be specified for a LOAD request.) 



Callers not authorized to use a specific service are abnormally terminated with a system abend 
codeofX'28A'. 
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Example 1 

Operation: Perform the page-load function for the 4096-byte virtual area starting at BUFFER. 
No ECB is supplied. 

PGSER R,LOAD,A=BUFFER,EA=BUFFER+4095 ,ECB=0 

Example 2 

Operation: Release the virtual area specified in the PSL located at LOADWORD. 
PGSER L , RELEASE , LA=LOADWORD 
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POST — Signal Event Completion 



Use the POST macro instruction to have the specified ECB (event control block) set to indicate 
the occurrence of an event. If this event satisfies the requirements of an outstanding WAIT or 
EVENTS macro instruction, the waiting task is taken out of the wait state and dispatched 
according to its priority. The bits in the ECB are set as follows: 

Bit 0 of the specified ECB is set to 0 (wait bit) by POST processing. 
Bit 1 is set to 1 (complete bit) by POST processing. 

Bits 2 through 31 are set to the specified completion code by POST processing. 
The POST macro instruction is written as follows: 



name 


name: sjrmbol. Begin name in column 1. 


h 


One or more blanks must precede POST. 


POST 




b 


One or more blanks must follow POST. 


ecb addr 


ecb addr: RX-type address, or register (1) or (2) - (12). 


,comp code 


camp code: symbol, decimal digit, or register (0) or (2) - (12). 
Range of values: 0 to 2^^-l 
Default: 0 


.RELATED = va/«e 


value: Any valid macro keyword specification. 



The explanation of the parameters is as follows: 
ecb addr 

specifies the address of the fuUword event control block representing the event. 

,comp code 

specifies the completion code to be placed in the event control block upon completion. 
,RELATED = va/Me 

specifies information used to self-document macro instructions by 'relating' functions or 
services to corresponding functions or services. The format and contents of the 
information specified are at the discretion of the user, and may be any valid coding 
values. 

The RELATED parameter is available on macro instructions that provide opposite 
services (for example, ATTACH/DETACH, GETMAIN/FREEMAIN, and 
LOAD/DELETE), and on macro instructions that relate to previous occurrences of the 
same macro instructions (for example, CHAP and ESTAE). 
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The RELATED parameter may be used, for example, as follows: 

WAITl WAIT 1,ECB=ECB,RELATED=( RESUME 1, 
'WAIT FOR EVENT' ) 



RESUMEl POST ECB,0,RELATED=( WAITl, 
•RESUME WAITER') 



Note: Each of these macro instructions will fit on one line when coded, so there is no 
need for a continuation indicator. 



Example 1 



Operation: Signal event completion with a default completion code. POSTECB is the address 
ofanECB. 



POST POSTECB 

Example 2 



Operation: Signal event completion with a completion code of X'7FF'. POSTECB is the 
address of an ECB. 

POST POSTECB, X'7FF' 
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RACHECK - Check RACF Authorization 



The RACHECK macro instruction is used to provide authorization checking when a user 
requests access to a RACF-protected resource. 

Systems using RACF Version 1, Release 6 or later, have the option to temporarily grant access 
requests to users who do not have sufKlcient authority instead of unconditionally denying 
requests. In this case, RACF issues a warning message instead of failing the request. RACF 
provides this option on an individual basis; installations can use the warning facility selectively 
via the WARNING = YES keyword of the RACDEF macro for that particular profile, without 
affecting the access control provided by other RACF profiles. 

RACHECK bypasses the warning processing if the OWNER keyword is specified, as this 
indicates that the request is coming from a RACF conmiand processor. 

Notes: 

1. Do not use the DSTYPE=M or OWNER parameters unless RACF Version 1, Release 4 or 
later is installed on your system. 

2. Do not use the ACCLVL or RACFIND parameters unless RACF Version 1. Release 5 or 
later is installed on your system. 

3. Only callers in 24-bit addressing mode can issue this macro. Callers executing in 31-bit 
addressing mode, who want to use the RACHECK function, can code the RACROUTE 
macro. 
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The standard form of the RACHECK macro instruction is written as follows: 



RACHECK 
b 



name: symbol. Begin name in column 1. 

One or more blanks must precede RACHECK. 

One or more blanks must follow RACHECK. 



ENTITY = (re,yo«i'ce name addr) 
,VOlJSER = voladdr 



,CLASS = 'classname' 
,CLASS = class name addr 

.RELEASE = number 

,ATTR = READ 
,ATTR = UPDATE 
,ATTR = CONTROL 
,ATTR = ALTER 

,ATTR = reg 

,DSTYPE = N 
,DSTYPE = V 
,DSTYPE = M 
,DSTYPE = T 

,INSTLN =parm list addr 

,OLDVOL = old vol addr 

,APPL= 'applname' 
,APPL = applname addr 

,OWNER = owner ID addr 

,KCCLy\. = {access value addr) 
,ACCLVL = {access value addr, 
parm list addr) 

,RACFIND = YES 
,RACFIND = NO 

.GENERIC = YES 
.GENERIC = ASIS 

,FILESEQ = reg 
,FILESEQ = «MmZ)er 

.,TAPELBL = STD 
,TAPELBL = BLP 
,TAPELBL = NL 

.STATUS = NONE 
.STATUS = ERASE 



resource name addr: A-type address, or register (2) - (12). 
vol addr: A-type address, or register (2) - (12). 

Note: VOLSER is required only for CLASS = 'DATASET' and DSTYPE 
not equal to M when a discrete profile name is used and only when 
ENTITY is also coded. 

'classname': 1-8 character name. 

class name addr: A-type address, or register (2) - (12). 

Default: CLASS = 'DATASET' 

number: 1.6 or 1.7 
Default: RELEASE = 1.6 

reg: register (2) - (12). 
Default: ATTR = READ 



Default: DSTYPE = N 



parm list addr: A-type address, or register (2) - (12). 

old vol addr: A-type address, or register (2) - (12). 
applruune addr: A-type address, or register (2) - (12). 

owner ID addr: A-type address, or register (2) - (12). 
access value addr: A-type address or register (2)-(12). 
parm list addr: A-type address or register (2)-(12). 



Default: GENERIC =ASIS 



reg: register (2) - (12). 
number: 1-9999 

Default: TAPELBL = STD 



Default: STATUS = NONE 
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The parameters are explained as follows: 

ENTITY = ( resource name addr) 

ENTITY = ( resource name addr ) specifies that RACF authorization checking is to be 
performed for the resource whose name is pointed to by the specified address. The 
resource name is a 44-byte DASD data set name for CLASS = 'DATASET' or a 6-byte 
volume serial number for CLASS = 'DASDVOL' or CLASS = TAPEVOL'. The length of 
all other resource names is determined from the class descriptor tables. The name must 
be left justified in the field and padded with blanks. 



By establishing and maintaining a resource profile, the resource manager can reduce the 
I/O required to perform RACF authorization checks on highly-accessed resources. 

,VOLSER = vo/ addr 

specifies the volume serial number, as follows: 

• For non-VSAM DASD data sets and tape data sets, this is the volimie serial number 
of the volume on which the data set resides. 

• For VSAM DASD data sets and tape data sets, this is the volume serial number of 
the catalog controlhng the data set. 

The field pointed to by the specified address contains the volume serial number padded to 
the right with blanks, if necessary, to make six characters. VOLSER= is only valid and 
must be suppUed with CLASS = 'DATASET', (unless DSTYPE = M is specified) and if 
ENTITY is also coded. 

jCLASS—'classname' 

,CLASS = classname addr 

specifies that RACF authorization checking is to be performed for a resource of the 
specified class. If an address is specified, the address must point to a one-byte field 
indicating the length of the classname, followed by the class name (for example 
DATASET, DASDVOL or TAPEVOL). 

,RELEASE = number 

specifies the RACF release level of the parameter list to be generated by this macro. 

Certain parameters can be specified only with particular releases. For instance, to use the 
RACHECK release 1.7 parameter FILESEQ you must be using RACF 1.7 on your 
system and specify RELEASE = 1.7. If you specify a parameter with an incompatible 
release level, the parameter will not be accepted by the macro processing. An error 
message will be issued at assembly time. For the parameters that are vaUd for 
RELEASE = 1.6 and later, see Figure 60 on page 254. 

The default is RELEASE = 1.6. 

When you specify the RELEASE keyword, checking is done at assembly time. 
Execution-time validation of the compatibility between the Ust and execute forms of the 
RACHECK macro can be done by your specifying the CHECK subparameter on the 
execute form of the macro. 
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,ATTR = READ 
,ATTR = UPDATE 
,ATTR = CONTROL 
,ATTR = ALTER 
,ATTR = reg 

specifies the access authority of the user or group permitted access to the resource for 
which RACF authorization checking is to be performed: 

READ - RACF user or group can open the resource only to read. 

UPDATE - RACF user or group can open the resource to write or read. 

CONTROL - For VSAM data sets, RACF user or group has authority equivalent to 
the VSAM control password. For non-VSAM data sets and other resources, RACF 
user or group has UPDATE authority. 

ALTER - RACF user or group has total control over the resource. 

If a register is specified, the register must contain one of the following codes in the 
low-order byte of the register: 

X'02' - READ 
X'04' - UPDATE 
X'08' - CONTROL 
X'80' - ALTER 

,DSTYPE = N 
,DSTYPE=V 
,DSTYPE=M 
,DSTYPE = T 

specifies the type of data set associated with the request: 

• N for non-VSAM 

• V for VSAM 

• M for model profile 

• T for tape 

If DSTYPE = T is specified and tape data set protection is not active, the processing will 
be the same as for RACHECK CLASS = 'TAPEVOL'. DSTYPE should only be specified 
for CLASS = 'DATASET'. 

Note: Do not specify DSTYPE = M unless RACF Version 1, Release 4 or later is 
installed on your system. 

,INSTLN =/>flrm list addr 

specifies the address of an area that is to contain parameter information meaningful to the 
RACHECK installation exit routine. This information is passed to the installation exit 
routine when it is given control from the RACHECK routine. 

The INSTLN parameter can be used by an application program acting as a resource 
manager that needs to pass information to the RACHECK installation exit routine. 
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,OLDVOL = old vol addr 

specifies a volume serial: 

• For CLASS = 'DAT ASET', within the same multivolume data set specified by 
VOLSER = . 

• For CLASS = 'TAPEVOL', within the same tape volume specified by ENTITY = . 

RACF authorization checking will verify that the OLDVOL specified is part of the same 
multivolume data set or tape volume set. 

The specified address points to the field that contains the volume serial number padded to 
the right with blanks, if necessary, to make six characters. 

,APPL= 'applname' 

, APPL = applname addr 

specifies the name of the application requesting authorization checking. The applname is 
not used for the authorization checking process but is made available to the installation 
exit routine(s) called by the RACHECK routine. If the address is specified, the address 
must point to an 8-byte field containing the application name left justified and padded 
with blanks. 

,OWNER = owner ID addr 

specifies a profile owner id that is compared with the profile owner id in the owner field 
of the RACF profile. If the owner names match, the access authority allowed for that 
userid is 'ALTER'. The address must point to an 8-byte field containing the owner name, 
left-justified and padded with blanks. 

If OWNER is specified, any WARNING and OPERATIONS attribute processing is 
bypassed. 

Note: Do not specify OWNER unless RACF Version 1, Release 4 or later is installed on 
your system. 

,A.CCLW\j~ (access value addr) 

,ACCLVL= (access value addr.parm list addr) 

specifies the tape label access level information for the MVS tape label functions. The 
access value pointed to by the specified address is a one byte length field, containing the 
value (0-8) of the length of the following data, followed by an eight-character string that 
will be passed to the RACHECK installation exit routines. The optional parameter list 
pointed to by the specified address contains additional information to be passed to the 
RACHECK installation exit routines. RACF does not inspect or modify this 
information. 

Note: Do not use the ACCLVL parameter unless RACF Version 1, Release 5 or later is 
installed on your system. 



Supervisor Services and Macro Instructions 



,RACFIND=YES 
,RACFIND = NO 

indicates whether or not the resource is protected by a discrete profile. The RACF 
processing and the possible return codes are given in Figure 59. Note that in all cases, a 
return code of X*OC' is also possible. 

Note: Do not use the RACFIND parameter unless RACF Version 1, Release 5 or later 
is installed on your system. 



Operand 



Generic Profile Checkii^ 
Inactive 



Generic Profile Checking 
Active 



RACFIND = YES 



Look for discrete profile; 
if found, exit with 
return code 00 or 08. 
If no discrete profile is 
found, exit with return 
code 08. 



Look for discrete profile; 

if found, exit with 

retium code 00 or 08. 

Look for generic profile; 

if found, exit with return code 00 

or 08. 

Exit with return code 08 if neither 
a discrete nor a generic profile 
is found. 



RACFIND = NO No checking. Exit Look for generic profile; 

with return code 04. if found, exit with 

return code 00 or 08. 
if not found, exit with 
return code 04. 



RACFIND not 
specified 



Look for discrete profile; 
if found, exit with 
return code 00 or 08. 
If no discrete profile is 
found, exit with return 
code 04. 



Look for discrete profile; 

if found, exit with 

return code 00 or 08. 

Look for generic profile; 

if found, exit with return code 00 

or 08. 

Exit with return code 04 if neither a 
discrete nor a generic profile is found. 



Figure 59. Types of Profile Checking Perfonned by RACHECK 

,GENERIC=YES 
,GENERIC = ASIS 

specifies whether the resource name is to be treated as a generic profile name. If 
GENERIC is specified with CLASS = DEFINE, NEWNAME, then GENERIC appUes to 
both the old and new names. GENERIC is ignored if the GENCMD option on the 
RACF SETROPTS command is not specified for the class (see RACF Command 
Language Reference). 

This keyword is designed primarily for use by RACF commands. 

• If GENERIC = YES is specified, the resource name is considered a generic profile 
name, even if it does not contain either of the generic characters: an asterisk (*) or a 
percent sign (%). 

• If GENERIC = ASIS is specified, the resource name is considered a generic only if it 
contains either of the generic characters: an asterisk (*) or a percent sign (%). 
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,FILESEQ =«Mm^)er 
,FILESEQ = re^ 

specifies the file sequence number of a tape data set on a tape volume or within a tape 
volume set. The value must be in the range 1 - 9999. If a register is specified, it must 
contain the file sequence number in the low-order half-word. If CLASS = 'DATASET' 
and DSTYPE=T are not specified, FILESEQ is ignored. 

,TAPELBL = STD 
,TAPELBL = BLP 
,TAPELBL = NL 

specifies the type of tape label processing to be done: 

• STD - IBM or ANSI standard labels. 

• BLP - bypass label processing. 

• NL - non-labeled tapes. 

For TAPELBL=BLP, the user must have the requested authority to the profile ICHBLP 

in the general resource class FACILITY. For TAPELBL = NL or BLP, the user will not 
be allowed to protect volumes with volume serial numbers in the format "Lnnnnn." 

This parameter is primarily intended for use by data management routines to indicate the 
label type from the LABEL keyword on the JCL statement. 

This parameter is valid only for CLASS = 'DATASET' and DSTYPE = T, or 
CLASS = TAPEVOL'. The default is TAPELBL = STD. 

,STATUS = NONE 
,STATUS = ERASE 

Specifies whether or not RACHECK is to return the erase status of the given data set. 
This parameter is valid only for CLASS =*DATASET' and a DSTYPE value other than 
T. The default is STATUS = NONE. 

Parameters For RELEASE = 1.6 and Later 

The RELEASE values for which a specific parameter is valid are marked with an *X'. 



Parameter 


RELEASE = 
L6 


RELEASE" 
1.7 


ACCLVL= 


X 


X 


APPL = 


X 


X 


ATTR = 


X 


X 


CLASS = 


X 


X 


DSTYPE = N, V, or 
M 


X 


X 


DSTYPE = T 




X 


ENTITY = 


X 


X 


FILESEQ = 




X 


GENERIC = 


X 


X 


INSTLN= 


X 


X 


OLD VOL = 


X 


X 


OWNER = 


X 


X 



Figure 60 (Part 1 of 2). RACHECK Parameters for RELEASE » 1.6 and Later 
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Parameter 


RELEASE = 
1.6 


RELEASE 
1.7 


RACFIND = 


X 


X 


RELEASE = 


X 


X 


STATUS = 




X 


TAPELBL= 




X 


VOLSER= 


X 


X 



Figure 60 (Part 2 of 2). RACHECK Parameters for RELEASE » 1.6 and Later 



Return Codes and Reason Codes 

When control is returned, register 15 contains one of the following return codes: 

Hexadecimal Meaning 
Code 

00 The user is authorized by RACF to obtain use of a 

RACF-protected resource. Register 0 
contains one of the following reason codes: 

00 indicates a normal completion. 

04 indicates STATUS = ERASE was specified and the 
data set is to be erased when scratched. Or the 
warning status of the resource was requested by the RACHECK 
issuer setting bit '10' at offset 12 decimal 
in the RACHECK parameter list and the resource is 
in warning mode. 

04 The specified resource is not protected by RACF. 

Register 0 contains the following 
reason code: 

00 indicates a normal completion. 

08 The user is not authorized by RACF to obtain use 

of the specified RACF-protected resource. 
Register 0 contains the following 
reason code: 

00 indicates a normal completion. 

04 indicates STATUS = ERASE was specified and the 
data set is to be erased when scratched. 

08 indicates DSTYPE = T or CLASS = 'TAPEVOL' 
was. specified and the user is not authorized 
to use the specified volume. 

OC indicates the user is not authorized to 

use the data set. 

10 indicates DSTYPE = T or CLASS = 'TAPEVOL' 
was specified and the user is not authorized 
to specify LABEL = (,BLP). 

OC The OLDVOL specified was not part of the multivolume 

data set defined by VOLSER, or it was not part of the 
same tape volume defined by ENTITY. 

64 Indicates that the CHECK subparameter of the RELEASE 

keyword was specified on the execute form of the RACHECK macro; 
however, the list form of the macro does not have the proper 
RELEASE parameter. Macro processing terminates. 
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Example 1 



Operation: Perform RACF authorization checking using the standard form, for a non-VSAM 
data set controlled by the catalog pointed to by register 8. Register 7 points to the data set 
name, and the RACF user is requesting the highest level of control over the data set. The 
"RACF-indicated" bit in the data set's DSCB is on. 

RACHECK ENTITy=( (R7) ) ,V0LSER=(R8) , CLASS= ' DATASET ' , 
ATTR=ALTER /RACFIND=YES 

Example 2 

Operation: Perform RACF authorization checking using the standard form, for a VSAM data 
set pointed to by register 8. Register 7 points to the data set name, and the RACF user is 
requesting the data set for read only. Register 4 points to an area containing additional 
parameter information. 

RACHECK ENTITY=( (R7) ) ,V0LSER=(R8) ,CLASS= ' DATASET' , 
DSTYPE=V, INSTLN= (R4 ) 

Example 3 

Operation: Using the standard form, perform RACF authorization checking for a tape volume 
for read access only. The tape volume is pointed to by register 8 and the volume's access level 
is in register 5. 

RACHECK ENTITy= ( ( R8 ) ) , CLASS= ' TAPEVOL ' , ATTR=READ , 
ACCLVL=( (R5) ) 
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RACHECK (List Form) 



The list form of the RACHECK macro instruction is written as follows: 



RACHECK 
b 



name: symbol. Begin name in column 1. 

One or more blanks must precede RACHECK. 

One or more blanks must follow RACHECK. 



ENTITY = (resource name addr) 
yOUSER=vol addr 



,CLASS= 'classname' 
,CLASS = class name addr 

.RELEASE = number 

,ATTR = READ 
,ATTR = UPDATE 
,ATTR = CONTROL 
,ATTR = ALTER 
,ATTR = re^ 

,DSTYPE = N 
,DSTYPE = V 
,DSTYPE = M 
,DSTYPE=T 

JNSTLN =/>arm list addr 

,OLDVOL = old vol addr 

,APPL= 'applname' 
,APPL = applname addr 

,OWNER = OH'«er ID addr 

,ACChWL = (access value addr) 
jACCLVL = (access value addr, 
parm list addr) 

,RACFIND=YES 
,RACFIND=NO 

.GENERIC = YES 
.GENERIC =ASIS 

,FILESEQ = reg 
,FILESEQ = «M/«6er 

,TAPELBL = STD 
,TAPELBL=BLP 
,TAPELBL=NL 

,STATUS = NONE 
,STATUS = ERASE 



resource name addr: A-type address. 
vol addr: A-type address. 

Note: VOLSER is required on either the list or the execute form of the 
macro, but only for CLASS = 'DATASET' and DSTYPE not equal to M 
when a discrete profile name is used. If required, VOLSER must be 
specified on either the list or the execute form of the macro. 

'classname': 1-8 character name. 

class name addr: A-type address, or register (2) - (12). 

Default: CLASS ='DATASET' 

number: 1.6 or 1.7 
Default: RELEASE =1.6 

reg: register (2) - (12). 
Default: ATTR = READ 



Default: DSTYPE = N 

parm list addr: A-type address. 

old vol addr: A-type address. 
(^plname addr: A-type address. 

owner ID addr: A-type address. 

access value addr: A-type address or register (2)-(12). 

parm list addr: A-type address or register (2)-(12). 

Default- GENERIC =ASIS 



reg: register (2) - (12). 
number: 1-9999 

Default: TAPELBL = STD 



Default: STATUS = NONE 



,MF = L 
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The parameters are explained under the standard form of the RACHECK macro instruction 
with the following exception: 

,MF-L 

specifies the list form of the RACHECK macro instruction. 
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RACHECK (Execute Form) 



The execute form of the RACHECK macro instruction is written as follows: 



name 


ruime: symbol. Begin name in column 1 . 


b 


One or more blanks must precede RACHECK. 


RACHECK 




b 


One or more blanks must follow RACHECK. 


ENTITY = (reiroMrce name addr) 
,\OUSEK = vol addr 


resource name addr: RX-type address, or register (2) - (12). 

vol addr: RX-type address, or register (2) - (12). 

Note: VOLSER is required on either the list or the execute form of the 

macro, but only for CLASS = 'DATASET' and DSTYPE not equal to M 

when a discrete profile name is used. If required. VOLSER must be 

specified on either the list or the execute form of the macro. 


.CLASS = 'classname' 
,CLASS = class name addr 


'classname': 1-8 character name. 

class name addr: RX-tjrpe address, or register (2) - (12). 

Default: CLASS = 'DATASET' 


.RELEASE = ( number, CUECYi) 
.RELEASE = number 
.RELEASE = (.CHECK) 


number: 1.6 or 1.7 
Default: RELEASE = 1.6 


,ATTR = READ 
,ATTR = UPDATE 
,ATTR = CONTROL 
,ATTR = ALTER 
,ATTR = reg 


reg: register (2) - (12). 
Default: ATTR = READ 


,DSTYPE = N 
,DSTYPE = V 
,DSTYPE = M 
,DSTYPE = T 


Default: DSTYPE = N 


.INSTLN =parm list addr 


parm list addr: RX-type address, or register (2) - (12). 


,OLD\OL = old vol addr 


old vol addr: RX-type address, or register (2) - (12). 


.APPL= 'applname' 
fAPPL = applname addr 


applname addr: RX-type address, or register (2) - (12). 


.OWNER = owner ID addr 


owner ID addr: RX-type address, or register (2) - (12). 


.ACCLVL = (accm value addr, 
parm list addr) 


access value addr: RX-type address or register (2)-(12). 
RX-type address or register (2)-(12). 
parm list addr: 


,RACFIND = YES 
,RACFIND = NO 




.GENERIC = YES 
.GENERIC = ASIS 


Default: GENERIC = ASIS 


,FILESEQ = re^ 
.FILESEQ = number 


reg: register (2) - (12). 
number: 1-9999 


,TAPELBL = STD 
,TAPELBL = BLP 
,TAPELBL = NL 


Default: TAPELBL=STD 


.STATUS = NONE 
.STATUS = ERASE 


Default: STATUS = NONE 


,MF=(E,c;?-/ addr) 


Ctrl addr: RX-type address, or register (1) or (2) - (12). 
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The parameters are explained under the standard form of the RACHECK macro instruction 
with the following exceptions: 

^ = {E,ctrl addr) 

specifies the execute form of the RACHECK macro instruction. 

,REL£AS£ = inumber,CHECK) 
,RELEASE = number 
,RELEASE = (,CHECK) 

specifies the RACF release level of the parameter list to be generated by this macro. 

Certain parameters can be specified only with particular releases. For instance, to use the 
RACHECK release 1.7 parameter FILESEQ you must be using RACF 1.7 on your 
system and specify RELEASE = 1.7. If you specify a parameter with an incompatible 
release level, the parameter will not be accepted by the macro processing. An error 
message will be issued at assembly time. For the parameters that are valid for 
RELEASE = 1.6 and later, see Figure 60 on page 254. 

The default is RELEASE = 1.6. 

When you specify the RELEASE keyword, checking is done at assembly time. 
Execution-time validation of the compatibility between the list and execute forms of the 
RACHECK macro can be done by your specifying the CHECK subparameter on the 
execute form of the macro. 

When CHECK processing is requested, if the size of the list-form expansion is not large 
enough to accommodate all parameters defined by the RELEASE keyword on the execute 
form of the macro, the execute form of the macro will not be done. Instead, a return 
code X'64' will be generated. 



260 Supervisor Services and Macro Instructions 



RACROUTE - MVS Router Interface 



The RACROUTE macro instruction is used to invoke the System Authorization Facility (SAF) 
MVS router, which conditionally directs control to the Resource Access Control Facility 
(RACF) when RACF is present. 

You can use RACROUTE to access the functions that are provided by the following RACF 
macros: RACHECK, and FRACHECK. In coding the RACROUTE macro instruction to 
access a particular RACF macro function, you must also use the necessary parameters from 
that macro on the RACROUTE macro instruction. For example, if you code RACROUTE to 
access the RACHECK function, you must code REQUEST = AUTH and any other required 
parameters and any optional ones you need from the RACHECK macro. RACROUTE 
validates that only the parameters applicable to the RACHECK macro have been coded. 

Notes: 

1. For RACF Version 1 Release 6, all parameters and parameter lists must reside below 16 
megabytes. 

2. For RACF Version 1 Release 7: 

If a caller is executing in 24-bit addressing mode, all parameters and parameter lists are 
assumed to reside below 16 megabytes. If a caller, however, is executing in 31-bit addressing 
mode, and is calling RACF via the RACROUTE macro instruction, RACF will assume that 
all parameters and parameter lists may reside above the 16 megabytes ( that is, that all 
parameter addresses are true 31-bit addresses). 

All parameter lists generated by the RACROUTE macro instruction are in a format that 
allows compiled code to be moved above 16 megabytes without recompilation. 

This 31 -bit support is available only when RACF is called via the RACROUTE, 
FRACHECK, or RAC STAT macro instructions. Any caller that uses the RACHECK macro 
instruction may be in 24-bit addressing mode only. RACF does not support this caller in 
31 -bit mode. 
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The standard form of the RACROUTE macro instruction is written as follows: 



name 


name: symbol. Begin name in column 1. 


b 


One or more blanks must precede RACROUTE. 


RACROUTE 




b 


One or more blanks must follow RACROUTE. 


REQUEST = AUTH 
REQUEST = FASTAUTH 




,REQSTOR = reqstor addt 


reqstor addr: A-type address or register (2) - (12). 
Default: zero. 

Note: If REQSTOR = is coded and RACF is installed, the RACF router 

table must be updated to match the operand. 


,SUBSYS = subsys addr 


subsys addr: A-type address or register (2) - (12). 

Note: If SUBSYS = is coded and RACF is installed, the RACF router table 
must be updated to match the operand. 


,WORKA = work area addr 


work area addr: A-type address or register (2) - (12). 


.RELATED = va/Me 


value: Any valid macro keyword specified. 


,LOC = BELOW 
,LOC=ANY 
,LOC= ABOVE 


Default: See parameter description. 

Note: LOC can be coded only if 

REQUEST = VERIFY or REQUEST = LIST is coded. 



In addition to the parameters described above, all parameters valid on the RACHECK, and FRACHECK macros are 
permitted on the RACROUTE macro. Depending on the parameter REQUEST = , some of these are required, some 
optional, and some are invalid. 



The parameters are explained as follows: 

REQUEST = AUTH 
REQUEST = FASTAUTH 

specifies a code that determines the RACF parameter list to be issued internally as well as 
the RACF routine to receive control. The permissible codes and their associated RACF 
macros are as follows: 

AUTH - RACHECK 
FASTAUTH -- FRACHECK 

For RACROUTE to work correctly, once you have chosen a REQUEST code you must 
also code (on the RACROUTE macro) the parameters that belong to the associated 
macro instruction. Please see the associated macro for the necessary parameters. 

Notes: 

1. Data areas returned by RACF to the caller will be either above or below the 16-megabyte line, 
depending upon the caller's addressing mode and the data area in question. 

,REQSTOR = re^5for addr 

specifies the address of an 8-byte character field containing the control point name (this 
address identifies a unique control point within a set of control points that exists in a 
subsystem). If this operand is coded and RACF is installed, the RACF router table must 
be changed to match the operand. If the table is not updated, the default to bypass 
RACF processing is taken. For a description of the RACF router table and the macro 
used to update it, see SPL: Resource Access Control Facility (RACF). 

If this operand is omitted, a string of eight blanks is assumed. 
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,SUBSYS = 5M%5 addr 

specifies the address of an 8-byte character field containing the calling subsystem's name, 
version, and release level. If this operand is coded and RACF is installed, the RACF 
router table must be changed to match the operand. If the table is not updated, the 
default to bypass RACF processing is taken. For a description of the RACF router table 
and the macro used to update it, see SPL: Resource Access Control Facility (RACF). 

If this operand is omitted, a string of eight blanks is assumed. 

, WORKA = work area addr 

specifies the address of a 512-byte work area for use by the MVS router and the RACF 
front end routine. 

,RELATED = value 

specifies information used to self-document macro instructions by "relating" functions or 
services to corresponding functions or services. The format and contents of the 
information specified is at the discretion of the user, and can be any vaUd coding value. 

Return Codes and Reason Codes 

When control is returned, register 15 contains one of the following return codes: 

Hexadecimal Code Meaning 

00 The requested seciirity function has completed successfully. In addition, if the requested 

function was 'AUTH', the authorization request was accepted. 

04 The requested function has not been processed. In addition, if the request was 'AUTH', 

the MVS router could neither accept nor fail the request. The following are possible 
reasons for a request not being processed. 

- The MVS router is not active. 

- The RACF front end routine detected that a null action was requested for the 
specified request type, resource type, and subsystem ID. 

- The request/resource/subsystem combination could not be found in the router table. 

- RACF is not active on the system, and RACFIND = YES was not specified, and 
there is no RACROUTE installation exit routine (or an exit originated a return code 
of 4). 

- RACF is active on the system, but no profile exists for the specified resource. 

08 The requested function was processed by RACF, the MVS router, or the router exit 

(ICHRTXOO) and failed. If the requested function was 'AUTH', the authorization 
request has been failed. If RACF is inactive for an 'AUTH' request with 
RACFIND = YES, then the MVS router fails the request. The RACF or router exit 
return code and reason codes are returned in the first two words of the RACROUTE 
input parameter list. 
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Example 1 



Operation: Invoke the MVS router to perform authorization checking using the standard form, 
for a non-VSAM data set pointed to by register 8. Register 7 points to the data set name and 
the RACF user is requesting the highest level of control over the data set. The 
"RACF-indicated" bit in the data set's DSCB is on. 

RACROUTE REQUEST=AUTH,WORKA=RACWK,ENTITY=( (R7) ) , X 
VOLSER= ( R8 ) , CLASS= ' DATASET ' , ATTR=ALTER , X 
RACFIND=YES 

RACWK DS CL512 

Example 2 

Operation: Invoke the MVS router to perform authorization checking using the standard form, 
for an IMS/VS transaction pointed to by register 5. The user requests only read access. The 
request is issued on behalf of the IMS/VS subsystem. 



RACROUTE REQUEST«=FASTAUTH , SUBS YS=SUBIMS , X 

WORKA=RACWK , ENTITY= ( R5 ) , X 

CLASS= • TIMS • ,WKAREA=FRACWK, X 
ATTR=READ 



SUBIMS DC CL8 ' IMS ' 
FRACWK DS 16F 
RACWK DS CL512 
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RACROUTE (List Fom) 



The list form of the RACROUTE macro instruction is written as follows: 



nomg 


name' symbol. Begin name in column 1. 


D 


yjiK or more uianKS musi preceoc ix/\v.>k.\j«j i c 


RACROUTE 




b 


One or more blanks must follow RACROUTE. 


KbvJUcsi =AU In 




REQUEST = FASTAUTH 




,KEQSTOK = regstor addr 


reqstor addr: A-type address. 




Default: zero. 




Note: If REQSTOR = is coded and RACF is installed, the RACF router 




table must be updated to match the operand. 


,SUBSYS=JM%£ addr 


sid>sys addr: A-type address. 




Note: If SUBSYS= is coded and RACF is installed, the RACF router table 




must be updated to match the operand. 


,WORKA= work area addr 


work area addr: A-type address or register (2) - (12). 


,RELATED = value 


valm: Any valid macro keyword specified. 



,MF = L 

In addition to the parameters described above, all parameters valid on the RACHECK, and FRACHECK macros are 
permitted on the RACROUTE macro. Depending on the parameter REQUEST =, some of these are required, some 
optional, and some are invalid. 



The parameters are explained under the standard form of the RACROUTE macro instruction 
with the following exception: 

,MF=L 

specifies the list form of the RACROUTE macro instruction. 
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RACROUTE (Execute Fonn) 



The execute form of the RACROUTE macro instruction is written as follows: 



neons 


name.' symbol. Begin name in column 1. 


b 


One or more blanks must precede RACROUTE. 


RACROUTE 




b 


One or more blanks must follow RACROUTE. 


REQUEST =AUTH 
K.£>V;UCi3 1 — Jr Aal AU irl 




,REQSTOR = reqstor addr 


reqstor addr: RX-type address or register (2) - (12). 
Default: zero. 

Note: If REQSTOR = is coded and RACF is installed, the RACF router 
table must be updated to match the operand. 


,^\J^SYS=subsys addr 


subsys addr: RX-type address or register (2) - (12). 

Note: If SUBSYS = is coded and RACF is installed, the RACF router table 
must be updated to match the operand. 


,WORKA = work area addr 


work area addr: RX-type address or register (2) - (12). 


.RELATED = va/Me 


value: Any valid macro keyword specified. 


,M^ = {'^,ctrl addr) 


Ctrl addr: RX-type address or register (1). 



In addition to the parameters described above, all parameters valid on the RACHECK, and FRACHECK macros are 
permitted on the RACROUTE macro. Depending on the parameter REQUEST =, some of these are required, some 
optional, and some are invalid. 



The parameters are explained under the standard form of the RACROUTE macro instruction 
with the following exception: 

,MF = (E, Ctrl addr) 

specifies the execute form of the RACROUTE macro where Ctrl addr is the address of the 
associated parameter list. 
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RACSTAT - 



RACF Status Extract Service 



The RACSTAT macro instruction is used to determine if RACF is active and optionally 
determine if RACF protection is in effect for a given resource class. The RACSTAT macro can 
also be used to determine if a resource class name is defined to RACF. 

RACSTAT is a branch entered service that uses standard linkage conventions. 

Note: For RACF release 1.6 and previous releases, only callers in 24-bit addressing mode can 
issue this macro. 

The standard form of the RACSTAT macro instruction is written as follows: 





name 


name: symbol. Begin name in column 1. 


b 




One or more blanks must precede RACSTAT. 


RACSTAT 




b 




One or more blanks must follow RACSTAT. 




CLASS = 'classname'. 


classname: DASDVOL, TAPEVOL, or any class defined in the RACF class 






descriptor table 




CLASS = classname addr. 


classname addr: A-type address, or register (2) - (12). 




ENTRY = e«rry addr 


entry addr: A-type address, or register (2) - (12). 




,RELEASE = number 


ntanber: 1.6 or 1.7 






Default: RELEASE= 1.6 



The parameters are explained as follows: 

CLASS = 'classname', 

CLASS = classname addr, 

specifies the classname for which RACF authorization checking is performed. The name 
can be explicitly defined on the macro by enclosing the name in quotes. If specified, the 
address must point to an 8-byte field containing the classname, left justified and padded 
with blanks if necessary. If CLASS = is omitted, the status of RACF is returned. 

"ENIKY^ entry addr 

specifies the address of a 4-byte area that is set to the address of the specified class in the 
class descriptor table. This operand is ignored when the CLASS = operand is omitted. 

,RELEASE = «Mw6er 

specifies the RACF release level of the parameter Ust to be generated by this macro. 

Certain parameters can be specified only with particular releases. If you specify a 
parameter with a^ incompatible release level, the parameter will not be accepted by the 
macro processing. An error message will be issued at assembly time. For the parameters 
that are valid for RELEASE = 1.6 and later, see Figure 61 on page 268. 

The default is RELEASE = 1.6. 

When you specify the RELEASE keyword, checking is done at assembly time. 
Execution-time validation of the compatibility between the list and execute forms of the 
RACSTAT macro can be done by your specifying the CHECK subparameter on the 
execute form of the macro. 
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Parameters For RELEASE = 1.6 and Later 

The RELEASE values for which a specific parameter is valid are marked with an *X'. 



Parameto* 


RELEASE » 
1.6 


RELEASE- 
1.7 


CLASS = 


X 


X 


ENTRY = 


X 


X 


RELEASE = 


X 


X 



Figure 61. RACSTAT Parameters for RELEASE = 1.6 and Later 



Return Codes 

When control is returned, register 15 contains one of the following return codes: 

Hexadecimal 

Code Meaning 

00 RACF is active and, if CLASS = was spedfied, the class is active. 

04 RACF is active; the class is inactive. 

08 RACF is active; the class is not defined to RACF. 

OC RACF is inactive and, if CLASS = was specified, the class is active. 

10 RACF is inactive; the class is inactive. 

14 RACF is inactive; the class is not defined to RACF. 

18 RACF CVT does not exist (RACF is not installed) or an insufficient level of RACF is installed. 

64 Indicates that the CHECK subparameter of the RELEASE keyword was specified on the execute form 

of the RACSTAT mao'o; however, the list form of the macro does not have the proper RELEASE 
parameter. Macro processing terminates. 

Reason Codes 

FRACHECK examines the auditing options in effect for the resource for which access authority 
is being determined. It sets a reason code that indicates to FRACHECK's caller whether 
logging of the access attempt should be performed: 

Hexadedmal 

Code Meaning 

00 The access attempt is not within the scope of the audit or the global audit specification. The user is 

either authorized or unauthorized for the resource as indicated by the return code. 

04 The access attempt is within the scope of the audit or the global audit specification for the resource. 

Logging of the attempt should be performed by issuing, for example, a RACHECK for the resource for 
which authorization is being determined. RACHECK provides the necessary logging function. 

Note: The class descriptor entry for the specified class is returned to the caller (in the 4-byte 
area addressed by the entry addr), for return codes 00, 04, OC, and 10. 
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Example 1 

Operation: Determine if the DASDVOL class is active and retrieve the address of its class 
descriptor. A fuUword, CDADDR, contains the class descriptor address. 

RACSTAT CLASS= ' DASDVOL ' , ENTRY=CDADDR 
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RACSTAT (List Form) 



The list form of the RACSTAT macro instruction is written as follows: 



name 

b 

RACSTAT 
b 


name: symbol. Begin name in column 1. 
One or more blanks must precede RACSTAT. 

One or more blanks must follow RACSTAT. 


CLASS = 'classname', 


classname: DATASET, DASDVOL, or TAPEVOL. 


CLASS = classname addr. 


classname addr: A-type address. 


ENTRY = entry addr. 


entry addr: A-type address. 


.RELEASE = number 


number: 1.6 or 1.7 




Default- RELEASE =1.6 


MF=L 





The parameters are explained under the standard form of the RACSTAT macro instruction 
with the following exception: 

MF = L 

specifies the list form of the RACSTAT macro instruction. 
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RACSTAT (Execute Form) 



The execute form of the RACSTAT macro is written as follows: 



name 


name: symbol. Begin name in column 1. 


b 


One or more blanks must precede RACSTAT. 


RACSTAT 




b 


One or more blanks must follow RACSTAT. 


CLASS = 'classname', 
CLASS = classname addr. 


classname: DATASET, DASDVOL. or TAPEVOL. 
classname addr: RX-type address or register (2) - (12). 


ENTRY = addr. 


entry addr: RX-type address or register (2) - (12). 


.RELEASE = ('nMW^>er.CHECK) 
.RELEASE = number 
.RELEASE = (.CHECK) 


•number: 1.6 or 1.7 
Default: RELEASE =1.6 


MF = (E.c/r/arfdr) 


Ctrl addr: RX-type address or register (1) - (12). 



The parameters are explained under the standard form of the RACSTAT macro instruction, 
with the following exception: 

MS = {E,ctrladdr) 

specifies the execute form of the RACSTAT macro instruction, using a remote control 
program parameter list. 

,RELEASE = («i/mZ>er,CHECK) 
,RELEASE = «MmZ>er 
,RELEASE = (,CHECK) 

specifies the RACF release level of the parameter list to be generated by this macro. 

Certain parameters can be specified only with particular releases. If you specify a 
parameter with an incompatible release level, the parameter will not be accepted by the 
macro processing. An error message will be issued at assembly time. For the parameters 
that are vaUd for RELEASE = 1.6 and later, see Figure 61 on page 268. 

The default is RELEASE =1.6. 

When you specify the RELEASE keyword, checking is done at assembly time. 
Execution-time validation of the compatibility between the list and execute forms of the 
RACSTAT macro can be done by your specifying the CHECK subparameter on the 
execute form of the macro. 

When CHECK processing is requested, if the size of the list-form expansion is not large 
enough to accommodate all parameters defined by the RELEASE keyword on the execute 
form of the macro, the execute form of the macro will not be done. Instead, a return 
code of X'64' will be generated. 
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RETURN — Return Control 



The RETURN macro instruction restores the control to the calling program and signals normal 
termination of the called program. The return of control is always made by executing a branch 
instruction using the address in register 14. Because the RETURN macro uses a BR 14 to pass 
control, it can be used only when the return is to a program that executes in the same 
addressing mode. The RETURN macro instruction can restore a designated range of registers, 
provide a return code in register 15, and flag the save area used by the called program. 

If registers are to be restored, or if an indicator is to be placed into the save area, register 13 
must contain the address of the save area, which must have the standard format. 

The RETURN macro instruction is written as follows: 



name 


name: symbol. Begin name in column 1 . 


b 


One or more blanks must precsede RETURN. 


RETURN 




b 


One or more blanks must follow RETURN. 


(regl) 
(regl,reg2) 

J 

,RC = ret code 


regl and reg2: decimal digits, and in the order 14, 15, 0 through 12. 


ret code: decimal digit, symbol, or register (15). The maximum value is 4095. 



The parameters are explained as follows: 

(regl) 
(regl,reg2) 

specifies the register or range of registers to be restored from the save area pointed to by 
the address in register 13. If you omit this parameter, the contents of the registers are not 
altered. Do not code this parameter when returning control from a program interruption 
exit routine. 

,T 

causes the control program to flag the save area used by the called program. The 
low-order bit of word 4 of the save area is set to 1 after the registers have been loaded; 
this designates that a called program has executed a return to its caller. Do not specify 
this parameter when returning control from an exit routine. 

,RC = re? code 

specifies the return code to be passed to the calling program. If a symbol or decimal digit 
is coded, the return code is placed right-adjusted in register 1 5 before return is made; if 
register 15 is coded, the return code has been previously loaded into register 15 and the 
contents of register 15 are not altered or restored from the save area. (If you omit this 
parameter, the contents of register 15 are determined by the regl and reg2 parameters.) 

Note: If register 15 is coded and a return code greater than 4095 (decimal) is passed, the 
results could be either an invalid return code in the message or invalid RC testing. 
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Example 1 

Operation: Restore registers 14-12, flag the save area, and return with a code of 0. 
RETURN (14,12) ,T,RC=0 
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SAVE — Save Register Contents 



The SAVE macro instruction stores the contents of the specified registers in the save area at the 
address contained in register 13. If you wish, you may specify an entry point identifier. Write 
the SAVE macro instruction only at the entry point of a program because the code resulting 
from the macro expansion requires that register 15 contain the address of the SAVE macro 
prior to its execution. Do not use the SAVE macro instruction in a program interruption exit 
routine. 



The SAVE macro instruction is written as follows: 



name 


name: symbol. Begin name in column 1. 


b 


One or more blanks must precede SAVE. 


SAVE 




b 


One or more blanks must follow SAVE. 


(regl) 


regl and reg2: decimal digits, and in the order 14, IS, 0 through 12. 


(regl,reg2) 




9 




,id name 


id name: character string of up to 70 characters or as an * 



The parameters are explained as follows: 



(regl) 
(regl,reg2) 

specifies the register or range of registers to be stored in the save area at the address 
contained in register 13. The registers are stored in words 4 through 18 of the save area. 

» 

,T 

specifies that registers 14 and 15 are to be stored in word 4 and 5, respectively, of the save 
area. This parameter permits you to save two noncontiguous sets of registers. 

If you specify both T and reg2, and regl is any of registers 14, 15, 0, 1, or 2, all of 
registers 14 through the reg2 value are saved. 

,id name 

specifies an identifier to be associated with the SAVE macro instruction. If an asterisk (*) 
is coded, the identifier is the name associated with the SAVE macro instruction, or, if the 
name field is blank, the control section name is used. The identifier aids in locating a 
program's save area in a dump. If the CSECT instruction name field is blank, the 
parameter is ignored. 

Whenever a symbol or an asterisk is coded, the following macro expansion occurs: 

• A count byte containing the number of characters in the identifier name is assembled four 
bytes following the address contained in register 15. 

• The character string containing the identifier name is assembled starting at five bytes 
following the address contained in register 15. 

• An instruction to branch around the coimt and identifier fields is assembled. 
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Example 1 

Operation: Save registers 14-12, and associate the identifier with the CSECT name. 
SAVE (14,12),,* 



SAVE — Save Register Contents 



SEGLD — Load Overlay Segment and Continue Processing 



The SEGLD macro instruction causes the control program to load the specified segment and 
any segments in its path that are not part of a path already in virtual storage. Control is not 
passed to the specified segment, but is returned to the instruction following the SEGLD macro 
instruction. Processing is overlapped with the loading of the segment. Refer to the Linkage 
Editor and Loader for details on overlay. 

Note: This macro can be used only by callers in 24-bit addressing mode. 
The SEGLD macro instruction is written as follows: 



name 


name: symbol. Begin /tame in column 1. 


b 


One or more blanks must precede SEGLD. 


SEGLD 




b 


One or more blanks must follow SEGLD. 


ext seg name 


ext seg norm: symbol. 



The parameters are explained as follows: 
ext seg name 

specifies tiie name of a control section or an entry name in the required section. An 
exclusive reference is not allowed. The name does not have to be identified by an 
EXTRN statement. 

Example 1 

Operation: Cause the control program to load segment PGM54. 
SEGLD PGM54 
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SEGWT - Load Overlay Segment and Wait 

The SEGWT macro instruction causes the control program to load the specified segment and 
any segments in its path that are not part of a path already in virtual storage. Control is not 
passed to the specified segment; control is not returned to the segment issuing the SEGWT 
macro instruction until the requested segment is loaded. Refer to the publication Linkage 
Editor and Loader for details on overlay operations. The SEGWT macro instruction cannot be 
used in an asynchronous exit routine. 

Note: This macro can be used only by callers in 24-bit addressing mode. 
The SEGWT macro instruction is written as follows: 



name 


name: symbol. Begin name in column 1. 


h 


One or more blanks must precede SEGWT. 


SEGWT 




b 


One or more blanks must follow SEGWT. 


ext seg name 


ext seg name: symbol. 



The parameters are explained as follows: 
ext seg name 

specifies the name of a control section or an entry name in the required section. An 
exclusive reference is not allowed. The name does not have to be identified by an 
EXTRN statement. 

Example 1 

Operation: Cause the control program to load segment PGMWT. 
SEGWT PGMWT 
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— Set Return Parameters 



The SETRP macro instruction is used to indicate the various requests that a recovery exit may 
make. It may be used only if a system diagnostic work area (SDWA) was passed to the 
recovery exit. The macro instruction is valid only for ESTAE/ESTAI exits. (The SDWA 
mapping macro - IHASDWA - must be included in the routine that issues SETRP.) 

The SETRP macro instruction is written as follows: 



name 

b 

SETRP 
b 



name: symbol. Begin name in column 1. 
One or more blanks must precede SETRP. 

One or more blanks must follow SETRP. 



,WKAREA = (r«:?) 

,REGS = (re^i) 
,KEGS = iregl.reg2) 



reg: decimal digits 1-12. 
Default: WKAREA = (1) 

regl: decimal digits 0-12, 14 IS. 
reg2: decimal digits 0-12, 14, IS. 

Note: If regl and reg2 are both specified, order is 14, IS, 0-12. 



,DUMP = IGNORE 
.DUMP = YES 
,DUMP = NO 

,DUMPOPT =/>arm list addr 



.REASON = cotfe 



Default: DUMP = IGNORE 



parm list addr: RX-type address, or register (2) - (12). 

Note: This parameter may be specified only if DUMP = YES is specified 

above. 

code: any four-byte niunber specified in decimal (31 -bit) or hexadecimal 
(32-bit). 



,RC = 0 
,RC = 4 
,RC=16 



Default: RC=0 



,RETADDR = mr;; addr 



,RETREGS = NO 
,RETREGS = YES 

,RETREGS = YES,RUB = reg info addr 

,FRESDWA = NO 
,FRESDWA = YES 

.COMPCOD = comp code 
,COMPCOD = (com/> code,XJSER) 
,COMFCOD = (comp code,SYSTEM) 



retry addr: RX-type address, or register (2) - (12). 

Note: This parameter may be specified only if RC = 4 is specified above. 

reg info addr: RX-type address, or register (2) - (12). 

reg info addr: RX-type address, or register (2) - (12). 
Default: RETREGS = NO 

Note: This parameter may be specified only if RC=4 is specified above. 
Default: FRESDWA = NO 

Note: This parameter may be specified only if RC = 4 is specified above. 

comp code: symbol, decimal digit, or register (2) - (12). 
Default: COMFCOD= (comp code,lJSER) 



The parameters are explained as follows: 
,WKAREA = (reg) 

specifies the address of the SDWA passed to the recovery exit. If this parameter is 
omitted the address of the SDWA must be in register 1. 
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,REGS = (regi) 
,REGS =(reg/,reg2) 

specifies the register or range of registers to be restored from the save area pointed to by 
the address in register 13. If REGS is specified, a branch on register 14 instruction will 
also be generated to return control to the control program. If REGS is not specified, the 
user must code his own return. 



,DUMP = IGNORE 
,DUMP = YES 
,DUMP = NO 

specifies that the dump option fields will not be changed (IGNORE), will be zeroed (NO), 
or will be merged with dump options specified in previous dump requests, if any (YES). 
If IGNORE is specified, a previous exit had requested a dump or a dump had been 
requested via the ABEND macro instruction, and the previous request will remain intact. 
If NO is specified, no dump will be taken. 

jDUMPOPT = parm list addr 

specifies the address of a parameter list that is valid for the SNAP macro instruction. The 
parameter list can be created by using the list form of the SNAP macro instruction, or a 
compatible list can be created. If the specified dump options include subpools for storage 
areas to be dumped, up to seven subpools can be dumped. Subpool areas are 
accumulated and wrapped, so that the eighth subpool area specified replaces the first. 
The TCB, DCB, and STRHDR options available on SNAP will be ignored if they appear 
in the parameter list. The TCB used will be the one for the task that suffered error. The 
DCB used will be one created by the control program and either SYSABEND, 
SYSMDUMP, or SYSUDUMP will be used as a DDNAME. 

,REASON = coi/e 

specifies the reason code that the user wishes to pass to subsequent recovery exits. 

,RC = 0 
,RC=4 
,RC = 16 

specifies the return code the user exit routine sends to recovery processing to indicate 
what further action is required: 

0 - Continue with termination, causes entry into previously specified recovery routine, if any. 

4 - Retry using the retry address specified. 

16 - Suppress fiirther ESTAI/STAI processing (for ESTAI only). 



,RETADDR = rerrv addr 

specifies the address of the retry routine to which control is to be given. 

,RETREGS = NO 
,RETREGS = YES 

,RETREGS = YES,RUB = reg info addr 

specifies the contents of the registers on entry to the retry routine. If NO is specified or 
defaulted, only parameter registers (14-2) are passed; all others are unpredictable. If YES 
is specified, the contents of the SDWASRSV field will be used to initialize registers 0-14 
when an FRR requests retry and registers 0-15 when an ESTAE requests a retry. For 
ESTAE exits, this field contains the registers at the last interruption of the RB level at 
which retry will occur. For ESTAI exits, the contents of SDAWSRSV must be set by the 
user either before SETRP is issued or by use of the RUB parameter; any field not set will 
cause the corresponding register to contain 0 on entry to the retry routine. 
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RUB specifies the address of an area (register update block) that contains register update 
information. The data specified in this area will be moved into the SDWA and will be 
loaded into the general purpose registers on entry to the retry routine. The maximum 
length of the RUB is 66 bytes. 

• The first two bytes represent the registers to be updated, register 0 corresponding to 
bit 0, register 1 corresponding to bit 1, and so on. The user indicates which of the 
registers are to be stored in the SDWA by setting the corresponding bits in these two 
bytes. 

• The remaining 64 bytes contain the update information for the registers, in the order 
0-15. If all 16 registers are being updated, this field consists of 64 bytes. If only one 
register is being updated, this field consists of only 4 bytes for that one register. 

For example, if only registers 4, 6, and 9 are being updated: 

• Bits 4, 6, and 9 of the first two bytes are set. 

• The remaining field consists of 12 bytes for registers 4, 6, and 9; the first 4 bytes are 
for register 4, followed by 4 bytes for register 6, and 4 final bytes for register 9. 

,FRESDWA = NO 
,FRESDWA = YES 

specifies that the entire SDWA be freed (YES) or not be freed (NO) prior to entry into 
the retry routine. 

.COMPCOD = comp code 
,COMPCOD (comp code,lJSER) 
,COMPCOD = {comp code,SYSTEM) 

specifies the user or system completion code that the user wishes to pass to subsequent 

recovery exits. 



Example 1 

Operation: Request continue with termination, suppress dumping, restore register 14 from the 
save area and pass control to the location it contains, contain the SDWA in the location 
addressed by register 3, and change the completion code to 10. 

SETRP RC=0,DUMP=NO,REGS=(14) ,WKAREA=(3) , X 
COMPCOD= ( X • OOA • , USER ) 

Example 2 

Operation: Retry using address X, take a dump before retry, use the contents of SDWASRSV 
to initialize the registers, free the SDWA before control is passed to the retry address, and 
restore registers 14-12. 

SETRP RC=4,RETREGS=YES,DUMP=YES,FRESDWA=YES, X 
REGS= (14,12), RETADDR=X 
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SNAP 



— Dump Virtual Storage and Continue 



You can use the SNAP macro instruction to obtain a dump of some or all of the storage 
assigned to the current job step. You can also dump some or all of the control program fields. 
The SNAP macro instruction causes the specified storage to be displayed in the addressing 
mode of the caller. 

You must provide a data control block and issue an OPEN macro instruction for the data set 
before any SNAP macro instructions are issued. The DCB macro instruction must contain the 
following parameters: 

DSORG=PS ,RECFM=VBA,MACRF=(W) ,BLKSIZE=nnn,LRECL=xxx, 
and DDNAME=any name but SYSABEND, SYSMDUMP or SYSUDUMP 

The DCB and TCB must reside in 24-bit addressable storage. All other parameters can reside 
above 16 Mb if the issuer is executing in 31 -bit addressing mode. 

If a standard dump of 120 characters per line is requested, BLKSIZE must be either 882 or 
1632, and LRECL must be 125. (The data control block and the DCB macro instruction are 
described in Data Management Services Guide and Data Management Macro Instructions.) A 
high-density dump printed on a 3800 Printing Subsystem has 204 characters per line. To obtain 
a high-density dump, you must code CHARS = DUMP on the DD statement describing the 
dump data set. The BLKSIZE = must be either 1470 or 2724, and the LRECL = must be 209. 
You can also code CHARS = DUMP on the DD statement describing a dimip data set that will 
not be printed immediately. If you specify CHARS = DUMP and the output device is not a 
3800, print Unes are truncated and print data is lost. If you open a SNAP data set in a problem 
program that will be processed by the system loader, your problem program must close the data 
set. 

There are three ways to obtain a dump: 

1. Spool the dump by specifying SYSOUT=x on the DD statement. The dump is printed 
without a separate job but is deferred until after the job ends. 

2. Select a tape or direct access device. This method requires a separate job step to print the 
dump. This method might be used if the dump is to be printed more than once. 

3. Select a printer on the DD statement. This method is almost never used because the printer 
cannot be used by anyone else for the duration of the job step. 

Both NUC and ALLVNUC are valid. Only ALLVNUC gives you the whole virtual nucleus. 
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The standard form of the SNAP macro instruction is written as follows: 



name 

b 

SNAP 
b 



name: symbol. Begin name in column 1. 
One or more blanks must precede SNAP. 

One or more blanks must follow SNAP. 



,TCB = tcb addr 
,ID = id nmbr 

,SDATA = ALL 
,SDATA = (j!yj data code) 



deb addr: A-type address, or register (2) - (12). 

tcb addr: A-type address, or register (2) - (12). 

id nmbr: symbol, decimal digit, or register (2) - (12). 
Value rai^e: 0-2SS 

sys data code: any combination of the following, separated by coromas. If you 
specify only one code, you do not need the parentheses. 



,PDATA=ALL 
,PDATA = (/>ro6 data code) 



NUC CB ERR 

SQA Q lO 

LSQA TRT ALLVNUC 
PCDATA 

SWA DM SUM 



prob data code: any combination of the following, separated by commas, 
you specify only one code, you do not need the parentheses. 



If 



.STORAGE = (jrr< addr, end addr) 
,UST = list addr 



^TRHDR= (hdr addr) 
,STRHDR=/rrfr list addr 



,SUBPLST = 5iip list addr 



PSW 
REGS 
SA or SAH 

JPA or LPA or ALLPA 
SPLS 

SUBTASKS 

strt addr: A-type address, or register (2) - (12). 
end addr: A-type address, or register (2) - (12). 
list addr: A-type address, or register (2) - (12). 

Note: One or more pairs of addresses may be specified, separated by commas. 
For example: 

STORAGE = (j/rr addr, end addr Mr t addr, end addr) 
hdr addr: A-type address, or register (2) - (12). 

Note: hdr addr is one or more addresses separated by commas. If you specify 
only one header address as an A-type address, you do not need the 
parentheses. If you specify one or more registers, then you must code double 
parentheses (one set enclosing each register and one set enclosing the list of 
registers). If STRHDR = (M/- addr) is specified, then STORAGE must also be 
specified. 

hdr list addr: A-type address, or register (2) - (12). 

Note: If STRHDR=/i(/r list addr is specified, then LIST must also be 

specified. 

sbp list addr: A-type address, or register (2) - (12). 



The parameters are explained as follows: 
DCB = deb addr 

specifies the address of a previously opened data control block for the data set that is to 
contain the dump. 

Note: DCB must reside in 24-bit addressable storage. 
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TCB = tcb addr 

specifies the address of a fullword on a fuUword boundary containing the address of the 
task control block for a task of the current job step. If omitted, or if the fullword 
contains 0, the dump is for the active task. If a register is designated, the register can 
contain 0 to indicate the active task, or can contain the address of a TCB. 

Note: TCB must reside in 24-bit addressable storage. 

ID = id nmbr 

specifies the number that is to be printed in the identification heading with the dump. If 
the number specified is not in the acceptable value range, it will not be printed properly in 
the heading. 

SDATA=ALL 
SDATA = {sys data code) 

specifies the system control program information to be dumped: 

ALL All of the SDATA options except ALLVNUC (The read-only portion of the nucleus is not 

included in the dump unless ALLVNUC is also specified as an option.) 

NUC The PSA, SQA, LSQA, and the read/write portion of the nucleus (if the entire nucleus is required, 

specify the ALLVNUC option.) 

Note: The CVT will be included if this option is specified. 
SQA The system queue area (subpools 226, 239, and 245). 

LSQA The local system queue area and subpools 229 and 230. 

SWA The scheduler work area related to the task (subpools 236 and 237). 

CB The control blocks for the task. 

Q The global resource serialization control blocks for the task. 

TRT The GTF trace and system trace data. If system tracing is active and the requestor is authorized, 

all system trace entries for all address spaces are included in the dump. Unauthorized requestors 
obtain those system trace entries, after the job-start time stamp in the ASCB, for their current 
address space. If GTF tracing is active, only the GTF trace entries for the current address space 
are included in the dump. 

DM Data management control blocks for the task. 

ERR Recovery/termination control blocks for the task. These control blocks summarize information 

that describes abnormal terminations of the task. 

lO Input/Output supervisor control blocks for the task. 

ALLVNUC The entire virtual nucleus, the PSA, LSQA, and SQA. (The NUC option will not dump the 
read-only section of the nucleus.) If the SNAP parameter list is used for a SYSMDUMP, the 
ALLVNUC option is converted to ALLNUC on the SVC dump parameter list. 

Note: The CVT is included if this option is specified. 

PCDATA Program call information for the task. 

The SUM option is valid for an abending task or on a list form of the SNAP macro 
instruction pointed to by the DUMPOf T keyword of the ABEND or SETRP macro 
instructions. The option SUM causes the dump to contain a summary dump. If SUM is 
the only option requested, the dump contains a dump header, control blocks, and the 
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other areas listed below. The header information, which is provided for all ABEND 
dumps, consists of the following information: 

• The dump title 

• The ABEND code and program status word (PSW) at the time of the error 

• If the PSW contains the address of an active load module: 

— The name and PSW address of the load module in error 

— The offset, into the load module, at which the error occurred 

The following control blocks and areas are also included in the dump: 

• The control blocks dumped for the CB option 

• The error control blocks (RTM2WAs and SCBs) 

• The save areas 

• The registers at the time of the error 

• The contents of the load module (if the PSW contains the address of an active load 
module) 

• The module pointed to by the last PRB (if it can be found) 

• IK of storage before and after the addresses pointed to by the PSW and the registers 
at the time of the error. 

Note: This storage will only be dumped if the caller is authorized to obtain it. The 
storage is printed by ascending storage addresses with duphcate addresses removed. 

• System trace entries after the job-start time stamp in the ASCB for the current 
address space. 

Note: The GTF trace records are not included. 

If other options are specified with SUM, the summary dump is dispersed throughout the 
dump. See the topic "SNAP Dumps" for an example of how this is done. 

,PDATA = ALL 

jPDATA = {prob data code) 

specifies the problem program information to be dumped: 

ALL All of the following fields. 

PSW Program status word when the SNAP or ABEND macro instruction was issued. 

REGS Contents of the floating-point registers and general-purpose registers when the SNAP or ABEND 

macro instruction was issued. Also, contents of the vector registers, vector status register, and the 
vector mask register when the SNAP or ABEND macro instruction was issued for any task that 
uses the Vector FaciUty. 

SA Save area linkage information, program call linkage, information, and a back trace through save 

areas. 
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SAH 



Save area linkage information and program call linkage information. 



JPA 



Contents of job pack area. 



LPA 



Contents of active link pack area for the requested task. 



ALLPA 



Contents of job pack area and active link pack area for the requested task. 



SPLS 



All virtual storage subpools (0-127,252). 



SUBTASKS The designated task and the program data information for all of its subtasks. 

jSTORAGE = (strt addr,end addr) 
,LIST = /i5r addr 

specifies one or more pairs of starting and ending addresses or a list of starting and 
ending addresses of areas to be dumped. Each starting address is rounded down to a 
fuUword boundary; each ending address is rounded up to a fuUword boundary. The area 
is then dumped in fuUword increments. Callers executing in either 24-bit or 31 -bit 
addressing mode must set the high-order bit of the fuUword containing the last address in 
this list to 1. Callers executing in 31 -bit addressing mode must ensure that this bit is 
cleared in all other addresses in the list because SNAP processing truncates the list at the 
first address that contains a 1 in the high order bit. 

,STVLHSR=-{hdr addr) 

,STRHDR = /ii/r list addr 

specifies one or more header addresses or the address of a Ust of header addresses. Each 
header address must be the address of a one byte header length field, which is followed by 
the text of the header. The header has a maximum length of 100 characters. 

If the STORAGE parameter was specified, the STRHDR (storage header) value must be 
one or more header addresses. The number of pairs of starting and ending addresses 
specified for STORAGE must be the same as the number of header addresses specified for 
STRHDR. If a header is not desired for a storage area, a comma must be used to 
indicate its absence. 

If the LIST parameter was specified, the STRHDR value must be the address of a list of 
header addresses. The Ust of addresses must begin on a fuUword boundary, and the high 
order bit of the fullword containing the last address of the list must be set to 1 . The 
number of pairs of starting and ending addresses suppHed with the LIST parameter must 
be the same as the nimiber of addresses in the Ust suppUed with STRHDR. If a header is 
not desired for a storage area, the STRHDR Ust must contain a zero address to indicate 
its absence. 

,SUBPLST = sbp list addr 

specifies the address of a Ust of subpool numbers to be dumped. Each entry in the Ust 
must be a two-byte entry and must specify a vaUd subpool number. The first halfword of 
the Ust must contain the number of subpools in the Ust and must be on a fullword 
boundary. If you specify an invaUd subpool number or a subpool number for which you 
do not have authorization, the number is skipped and you receive a comment in the dump 
output indicating the error. If a subpool contains 4k blocks of data that are mapped 
from a linear data set, the dump includes only the blocks that have changed since the 
last DIV SAVE function was invoked. 

Note: A maximum of seven subpool numbers is permitted on the Ust form of the SNAP 
macro instruction pointed to by the DUMPOPT keyword of ABEND or SETRP. 
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Control is returned to the instruction following the SNAP macro instruction. When control is 
returned, register 15 contains one of the following return codes: 

Hexadedmal 

Code Meaniiig 

00 Successful completion. 

04 Data control block was not open, or an invalid page exception occurred during the validity check of the 

DCB parameters. 

08 Task control block address was not valid, an invalid page reference occurred during the validity check of 

the TCB address, a subtask is a job step task, sufficient storage was not available, or the READ for 
JFCB or JFCBE failed. In all cases, the dump is canceled. (Message IEA997I is issued when the 
READ for JFCB or JFCBE fails.) 

OC Data control block type (DSORG, RECFM, MACRF, BLKSIZE, or LRECL) was incorrect, or the 

DCB's BLKSIZE and/or LRECL were not compatible with the dimip format options specified on the 
dump-related DD statement. 

Example 1 

Operation: Dump the storage ranges pointed to by register 9, and dump all PDATA and 
SDATA options. 

SNAP DCB= ( 8 ) , TCB= ( 5 ) , PDATA=ALL , SDATA=ALL , LIST= ( 9 ) 

Example 2 

Operation: Dump the storage ranges pointed to by register 9, and dump only the trace table 
and enqueue control blocks. 

SNAP DCB=(8) ,TCB=(5) ,ID=4,LIST=(9) , SDATA= ( TRT , Q ) 

Example 3 

Operation: Dump storage area 1000-2000 with no header, and dimip storage area 3000-4000 
with a header of 'USER LABEL ONE'. The comma specified in the value for STRHDR 
indicates that no header is wanted for storage area 1000-2000. 

SNAP DCB= (8 ) ,STORAGE=( 1000, 2000, 3000,4000 ) , X 
STRHDR=(,L1) 



LI DC ALl(L'HDRl) 

HDRl DC C'USER LABEL ONE' 
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Example 4 



Operation: Dump storage area 1000-1999 with a header of 'LABEL ONE' and dump storage 
area 3000-3999 with a header of 'LABEL TWO'. 

SNAP DCB= ( 8 ) , LIST=X , STRHDR=L1 



X 


DC 


A(IOOO) 


Start address 




DC 


A(1999) 


End address 




DC 


AOOOO) 


Start address 




DC 


X'80' 


End of list indicator 




DC 


AL3(3999) 


End address 


LI 


DC 


A (HDRl) 


Address of length label 
header one 




DC 


X'80' 


End of list 




DC 


AL3(HDR2) 


Address of length label 
header two 


HDRl 


DC 


AL1(L' HDRIA) 


Length of header one 


HDRIA 


DC 


C LABEL ONE' 


Header one 


HDR2 


DC 


AL1(L'HDR2A) 


Length of header two 


HDR2A 


DC 


C LABEL TWO' 


Header two 



Example 5 

Operation: Dump subpool 0, 1, and 2 storage related to the current TCB. 
SNAP DCB=XYZ,TCB=0,SUBPLST=SUBADDR 



SUBADDR DS OF 

DC X'0003' 
DC X'OOOC 
DC X'OOOl' 
DC X'0002' 



Fullword boundary 

Number of entries in the list 

Subpool 0 

Subpool 1 

Subpool 2 
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SNAP (List Form) 



Use the list form of the SNAP macro to construct a control program parameter list. You can 
specify any number of storage addresses using the STORAGE parameter. Therefore, the 
number of starting and ending address pairs in the list form of SNAP must be equal to the 
maximum number of addresses specified in any execute form of the macro, or a DS instruction 
must immediately follow the list form to allow for the maximum number of addresses. 

The Ust form of the SNAP macro instruction is written as follows: 



name name: symbol. Begin name in column 1 . 

b One or more blanks must precede SNAP. 
SNAP 

b One or more blanks must follow SNAP. 



DCB = deb addr deb addr: A-type address. 

,ID = id nmbr id mnbr: symbol or decimal digit. 

Value range: 0-2SS 

,SDATA = ALL 

,SDATA=(jyj data eode) sys data code: any combination of the following, separated by conmias. If you 

specify only one code, you do not need parentheses. 



NUC CB ERR 

SQA Q 10 

LSQA TRT ALLVNUC 
PCDATA 

SWA DM SUM 

,PDATA = ALL 

,'PDATA= (prob data code) prob data code: any combination of the following, separated by commas. If 

you specify only one code, you do not need parentheses. 



.STORAGE = (strt addr. end addr) 
,UST = list addr 



,STRUDR= (hdr addr) 

,STRHDR=hdr list addr 

,SUBPLST=jfe/> list addr 
,MF = L 



PSW 
REGS 
SA or SAH 

JPA or LPA or ALLPA 
SPLS 

SUBTASKS 

strt addr: A-type address. 
end addr: A-type address. 
list addr: A-type address. 

Note: One or more pairs of addresses may be specified, separated by conmias. 
For example: 

STORAGE = (strt addr, end addr .strt addr. end addr) 
hdr addr: A-type address. 

Note: hdr addr is one or more addresses separated by commas. If you specify 
only one header address, you do not need the parentheses. If STRHDR = {hdr 
addr) is specified, then STORAGE must also be specified. 

hdr list addr: A-type address. 

Note: If STRHDR = /zfi?r list addr is specified, then LIST must also be 
specified. 

sbp list addr: A-type address. 
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The parameters are explained under the standard form of the SNAP macro instruction, with the 
following exception: 

,MF=L 

specifies the list form of the SNAP macro instruction. 



SNAP (List Form) 289 



SNAP (Execute Fonii) 



A remote control program parameter list is referred to and can be modified by the execute form 
of the SNAP macro instruction. 

If you code only the DCB, ID, MF, or TCB parameters in the execute form of the macro 
instruction, the bit settings in the parameter list corresponding to the SDATA, PDATA, LIST, 
and STORAGE parameters are not changed. However, if you code the SDATA, PDATA, or 
LIST parameters, the bit settings for the coded parameter from the previous request are reset to 
zero, and only the areas requested in the current macro instruction are dumped. 

The execute form of the SNAP macro instruction is written as follows: 



name 

b 

SNAP 
b 



name: symbol. Begin name in column 1. 
One or more blanks must precede SNAP. 

One or more blanks must follow SNAP. 



T>C&~dcb addr 

,lCR = tcbaddr 
,TCB = 'S' 
,ID = id nmbr 

.SDATA = ALL 
,SDATA=(jyi data code) 



deb addr: RX-type address, or register (2) - (12). 
tcb addr: RX-type address, or register (2) - (12). 

id nmbr: symbol, decimal digit or register (2) - (12). 
Valne range: 0-2SS 

sys data code: any combination of the following, separated by commas. If you 
specify only one code, you do not need parentheses. 

NUC CB ERR 

SQA Q lO 

LSQA TRT ALLVNUC 
PCDATA 

SWA DM SUM 



,PDATA = ALL 
,PDATA = (pro6 data code) 



prob data code: any combination of the following, separated by commas, 
you specify only one code, you do not need parentheses. 

PSW 
REGS 
SA or SAH 

JPA or LPA or ALLPA 
SPLS 

SUBTASKS 



If 



.STORAGE = {strt addr. end addr) 
yUST^ list addr 



,STKaDK= (hdr addr) 



,S'TKaDK = hdr list addr 



,SUBPLST = sbp list addr 
,MF = iE,ctrladdr) 



strt addr: RX-type address, or register (2) - (12). 
end addr: RX-type address, or register (2) - (12). 
list addr: RX-type address, or register (2) - (12). 

Note: One or more pairs of addresses may be specified, separated by commas. 
For example: 

STORAGE = (strt addr. end addr, strt addr, end addr) 
hdr addr: RX-type address, or register (2) - (12). 

Note: hdr addr is one or more addresses separated by commas. If you specify 
only one header address as an RX-type address, you do not need the 
parentheses. If you specify one or more registers, then you must code double 
parentheses (one set enclosing each register and one set enclosing the list of 
registers). If STRHDR = (hdr addr) is specified, then STORAGE must also be 
specified. 

hdr list addr: RX-type address, or register (2) - (12). 

Note: If STRHDR = hdr list addr is specified, then LIST must also be 

specified. 

sbp list addr: RX-type address, or register (2) - (12). 
Ctrl addr: RX-type address, or register (1) or (2) - (12). 
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The parameters are explained under the standard form of the SNAP macro instruction, with the 
following exceptions: 

,TCB = *S' 

specifies the task control block of the active task. 

Note: TCB = 'S' causes a dump of the active task if this is the first use of the list form of 
the SNAP macro instruction or if the TCB specified on a previous execute form of the 
SNAP macro instruction was the current TCB or TCB = 'S'. 

M^ = (E,ctrl addr) 

specifies the execute form of the SNAP macro instruction using a remote control program 
parameter Ust. 
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SPIE — Specify Program Interruption Exit 



The SPIE macro instruction specifies the address of an interruption exit routine and the 
program interruption types that are to cause the exit routine to be given control. If the 
program interruption types specified can be masked, the corresponding program mask bit in the 
PSW (program status word) is set to I . If a maskable interruption is not specified, the 
corresponding bit in the PSW is set to 0. 

Only callers in 24-bit addressing mode can issue the SPIE macro instruction. If a caller in 
31 -bit addressing mode issues a SPIE macro instruction, the caller is abended with a system 
completion code of X'30E'. Callers in 31 -bit addressing mode must use the ESPIE macro 
instruction, which performs the same function as the SPIE macro instruction for callers in both 
24-bit and 31 -bit addressing mode. The ESPIE macro instruction is described in Part II of this 
book. For additional information concerning the relationship between the SPIE and the ESPIE 
macro instructions, see the section on program interruption processing, in Part I. 

Each succeeding SPIE macro instruction completely overrides any previous SPIE macro 
instruction specifications for the task. The specified exit routine is given control in the key of 
the TCB (TCBPKF) when one of the specified program interruptions occurs in any problem 
program of the task. When a SPIE macro instruction is issued from a SPIE exit routine, the 
program interruption element (PIE) is reset (zeroed). Thus, a SPIE exit routine should save any 
required PIE data before issuing a SPIE. If a caller issues an ESPIE macro instruction from 
within a SPIE exit routine, it has no effect on the contents of the PIE. However, if an ESPIE 
macro instruction deletes the last SPIE/ESPIE environment, the PIE is freed and the SPIE exit 
cannot retry. 

If the current SPIE environment is cancelled during SPIE exit routine processing, the control 
program will not return to the interrupted program'when the SPIE program terminates. 
Therefore, if the SPIE exit routine wishes to retry within the interrupted program, a SPIE 
cancel should not be issued within the SPIE exit routine. 

The SPIE macro instruction can be issued by any problem program being executed in the 
performance of the task. The control program automatically deletes the SPIE exit routine when 
the request block (RB) that issued the SPIE macro instruction terminates. If a caller attempts 
to delete a SPIE environment established under a previous RB, the caller is abended with a 
system completion code of X'46D'. 

Note: In MVS/370 the SPIE environment existed for the Ufe of the task. In MVS/XA, the 
SPIE enviromnent is deleted when the request block that issued the macro is deleted. That is, 
when a program running under MVS/XA completes, any SPIE environments created by the 
program are deleted. This might create an incompatibility with MVS/370 for programs that 
depend on the SPIE environment remaining in effect for the life of the task rather than the 
request block 

A PICA (program interruption control area) is created as part of the expansion of SPIE. The 
PICA contains the exit routine's address and a code indicating the interruption types specified 
in SPIE. 

If a SPIE environment was active, the SPIE service routine returns the address of the previous 
PICA in register 1; if an ESPIE environment was active, the SPIE service routine returns the 
address of a fake PICA in register 1. The contents of the fake PICA are impredictable. If no 
SPIE/ESPIE environment was active, the service routine returns a zero. 
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For more information on the SPIE macro and its control blocks, see the section on program 
interruption processing. 

The standard form of the SPIE macro instruction is written as follows: 



name name: symbol. Begin nam& in column 1. 

b One or more blanks must precede SPIE. 
SPIE 

b One or more blanks must follow SPIE. 



exit addr,(interrupts) exit addr: A-type address, or register (2) - (12). 

interrupts: decimal digits, 1-1 S, expressed as: 

single values: (2,3,4,7,8,9,10) 
ranges of yalues: ((2,4),(7,10)) 
combinations: (2,3,4,(7,10)) 



The parameters are explained as follows: 
exit addr^iinterrupts) 

specifies the address of the exit routine to be given control when a program interruption 
of the type specified occurs. The interruption types are: 



Number 


Interruption Type 


1 


Operation 


2 


Privileged operation 


3 


Execute 


4 


Protection 


5 


Addressing 


6 


Specification 


7 


Data 


8 


Fixed-point overflow (maskable) 


9 


Fixed-point divide 


10 


Decimal overflow (maskable) 


11 


Decimal divide 


12 


Exponent overflow 


13 


Exponent underflow (maskable) 


14 


Significance (maskable) 


15 


Floating-point divide 



Notes: 

1. If an exit address is zero or no parameters are specified, the SPIE environment is cancelled. 

2. If a program interruption type is maskable, the corresponding bit is set to 1 when specified 
and to 0 when not specified. Interruption types that are not maskable and not specified above 
are handled by the control program, which forces an abend with the program check as the 
completion code. If an ESTAE-type recovery routine is also active, the SDWA indicates a 
system-forced abnormal termination. The registers at the time of the error are those of the 
control program. 

3. As shown in the table above, interruption types can be designated as one or more single 
numbers, as one or more pairs of numbers (designating ranges of values), or as any 
combination of the two forms. For example, ( 4,8 ) indicates interruption types 4 and 8; 
((4,8)) indicates interruption types 4 through 8. 
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4. For both ESPIE and SPIE — If you are using vector instructions and an exception of 8, 12, 
13, 14, or 15 occurs, your recovery routine can check the exception extension code ( the first 
byte of the two-byte interruption code in the EPIE or PIE) to determine whether the 
exception was a vector or scalar type of exception. 

Example 1 

Operation: Give control to an exit routine for interruptions 1, 5, 7, 8, 9, and 10. DOITSPIE is 
the address of the SPIE exit routine. 

SPIE DOITSPIE, (1,5,7, (8,10) ) 
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SPI£ (list Form) 



Use the list form of the SPIE macro instruction to construct a control program parameter list in 
the form of a program interruption control area. 

The list form of the SPIE macro instruction is written as follows: 



name 

b 

SPIE 
b 


name: symbol. Begin name in column 1. 
One or more blanks must precede SPIE. 

One or more blanks must follow SPIE. 


exit addr. 


exit addr: A-type address. 


{internets). 


interrupts: decimal digits, 1-1 S, expressed as: 




single values: (2,3,4,7,8,9,10) 




ranges of values: ((2,4),(7,10)) 




combinations: (2,3,4,(7,10)) 


MF = L 





The parameters are explained under the standard form of the SPIE macro instruction, with the 
following exception: 

MF = L 

specifies the list form of the SPIE macro instruction. 
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SPIE (Execute Form) 



A remote control program parameter list, the program interruptions control area (PICA) is used 
in, and can be modified by, the execute form of the SPIE macro instruction. The PICA can be 
generated by the hst form of SPIE, or you can use the address of the PICA returned in register 
1 following a previous SPIE macro instruction. If this macro instruction is being issued to 
reestabUsh a previous SPIE environment, code only the MF parameter. 

The address of the remote control program parameter list associated with any previous SPIE 
environment is returned by the SPIE macro instruction. 

The execute form of the SPIE macro instruction is written as follows: 



name 


name: symbol. Begin name in column 1. 


h 


One or more blanks must precede SPIE. 


SPIE 




b 


One or more blanks must follow SPIE. 


exit addr, 
(interrupts). 


exit addr: RX-type address, or register (2) - (12). 
interrupts: decimal digits, 1-1 S, expressed as: 

single values: (2,3,4,7,8,9,10) 
ranges of values: ((2,4),(7,10)) 
combinations: (2,3,4,(7,10)) 


MF = (E,ctrl addr) 


Ctrl addr: RX-t3^e address, or register (1) or (2) - (12). 



The parameters are explained under the standard form of the SPIE macro instruction, with the 
following exception: 

MF = {E.,ctrl addr) 

specifies the execute form of the SPIE macro instruction using a remote control program 
parameter list. 

Note: If SPIE is coded with a 0 as the control address, the SPIE environment is cancelled. 
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SPLEVEL - SET and TEST Macro Level 



Specific macro instructions supplied in the MVS/XA macro library are identified as downward 
incompatible (to MVS/370 System Product Version 1 Release 3). Unless the user takes specific 
action, these macros generate downward incompatible statements. It is possible to cause the 
generation of downward compatible expansions of these macros by using the SPLEVEL macro 
instruction. The downward incompatible macro instructions interrogate a global symbol (set by 
SPLEVEL) during assembly to determine the type of expansion to be generated. See the topic 
"Selecting the Macro Level" for additional information concerning the downward incompatible 
macro instructions and Assembler H Version 2 Application Programming: Language Reference 
for information about global set symbols. 

The SPLEVEL macro instruction is written as follows: 



name 


name: symbol. Begin name in column 1. 


b 


One or more blanks must precede SPLEVEL. 


SPLEVEL 




b 


One or more blanks must follow SPLEVEL. 


SET=« 


n: 1 or 2. 


SET 


Default: SET =2 


TEST 





The parameters are explained as follows: 

SET=« 

SET 

TEST 

specifies whether the macro level is being set or tested. 

If SET = « is specified, SPLEVEL processing sets a global set symbol equal to n, where n 
must be 1 or 2. If a user codes one of the downward incompatible macros, one of the 
following macro expansions is generated: 

• the MVS/370 (System Product Version 1 Release 3) macro expansion if n = 1 

• the MVS/XA macro expansion if « = 2 

If SET is specified without n, the SPLEVEL routine uses the default value, which is 2, 
unless the installation has changed the default. 

The TEST option is used to determine the macro level that is in effect. The results of the 
test request are returned to the user in the global set symbol, &SYSSPLV, which is 
defined by "GBLC &SYSSPLV." If TEST is specified and if SPLEVEL SET has not been 
issued during this assembly, SPLEVEL processing puts the default value into the global 
set symbol. If SPLEVEL SET has been issued, the previous value of n or the default 
value is already in the global set symbol. 
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Example 1 

Operation: Seiect the MVS/370 version of a specific downward incompatible macro instruction. 
SPLEVEL SET=1 

Example 2 

Operation: Select the MVS/XA version of a specific downward incompatible macro instruction. 
SPLEVEL SET=2 
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STATUS — Change Subtask Status 



The STATUS macro instruction lets the progranuner change the dispatchability status of one or 
all of a program's subtasks. For example, the STATUS macro instruction can be used to 
restart subtasks that were stopped when an attention exit routine was entered. 

The STATUS macro instruction is written as follows: 



name 


name: symbol. Begin nom^ in column 1. 


b 


One or more blanks must precede STATUS. 


STATUS 




b 


One or more blanks must follow STATUS. 


START 




STOP 




,i:CQ = tcb addr 


tcb addr: RX-type address, or register (2) - (12). 


.RELATED = va/«e 


value: Any valid macro keyword specification. 



The parameters are explained as follows: 

START 
STOP 

specifies that the START or STOP count in the task control block specified in the TCB 
parameter will be decreased (for START) or increased (for STOP) by 1. If the TCB 
parameter is not coded, the count is decreased/increased by 1 in the task control blocks 
for all the subtasks of the originating task. 

Note: This parameter does not assure that the subtask(s) is stopped when control is 
returned to the issuer. A subtask can have a "stop deferred" condition that would cause 
that particular subtask to remain dispatchable until stops are no longer deferred. In an 
MP environment, it would be possible to have a task issue the STATUS macro with the 
STOP parameter and resume processing while the subtask (for which the STOP was 
issued) is re-dispatched to another processor. 

,TCB = rc* addr 

specifies the address of a fuUword on a fuUword boundary containing the address of the 
task control block that is to have its START/STOP count adjusted. (If a register is 
specified, however, the address is of the TCB itself.) If this parameter is not coded, the 
count is adjusted in the task control blocks for all the su^btasks of the originating task. 

Note: TCB must reside in 24-bit addressable storage. 

,R£LAT£D = va/u£ 

specifies information used to self-document macro instructions by "relating" functions or 
services to corresponding functions or services. The format and contents of the 
information specified are at the discretion of the user, and may be any valid coding 
values. 

The RELATED parameter is available on macro instructions that provide opposite 
services (for example, ATTACH/DETACH, GETMAIN/FREEMAIN, and 
LOAD/DELETE), and on macro instructions that relate to previous occurrences oif the 
same macro instructions (for example, CHAP and ESTAB). 



STATUS — Chang? Subtask Status 299 



Example 1 



Example 2 



The RELATED parameter may be used, for example, as follows: 

STATl STATUS STOP , TCB=YOURTCB , RELATED= ( STAT2 , 

•STOP A SUBTASK' ) 



STAT2 STATUS START, TCB=YOURTCB,RELATED=( STATl, 

■START A SUBTASK' ) 

Note: Each of these macro instructions will fit on one Une when coded, so there is no 
need for a continuation indicator. 



Operation: Stop all subtasks. 
STATUS STOP 



Operation: Stop a specific subtask. WHERETCB is a fuUword specifying the address of a 
subtask TCB. 



STATUS STOP , TCB=WHERETCB 

Example 3 

Operation: Start a specific subtask. WHERETCB is a fuUword specifying the address of a 
subtask TCB. 

STATUS START, TCB=WHERETCB 
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STIMER — Set Interval Timer 



This macro can be assembled compatibly between MVS/XA and MVS/370 through the use of 
the SPLEVEL macro instruction. Default processing will result in an expansion of the macro 
that operates only with MVS/XA. See the topic "Selecting the Macro Level" for additional 
information. 

If your program is to execute in 3 1 -bit addressing mode, you must use the MVS/XA version of 
this macro instruction. 

The STIMER macro instruction is used to set a timer to a specified time interval (less than or 
equal to 24 hours) or to an interval that will expire at a specified time of day (not to exceed 
24:00:00:00). An optional asynchronous timer completion exit is given control when the time 
interval expires; if no asynchronous timer completion routine is specified, no indication that the 
time interval has expired is provided. Only one time interval per task is in effect at a time, ' 
using STIMER, however, using STIMERM in conjunction with STIMER allows 17 separate 
intervals to be associated with a task. A second STIMER macro instruction issued before the 
first time interval expires overrides the first interval and exit routine. If a timer exit routine 
issues an STIMER macro instruction specifying the same exit routine, an infinite loop might 
result. 

The time interval may be a 'real-time interval' (measured continuously in real time via the clock 
comparator), or a 'task time interval' (measured, only while the task is in execution, via the 
CPU timer). If a real time interval is specified, the task may elect to either continue (REAL) or 
suspend (WAIT) execution during the interval. If the task elects to continue execution, it may 
optionally specify an exit routine to be given control on completion of the time interval. If the 
task elects to suspend execution, it is restarted at the next sequential instruction on completion 
of the time interval. If a task time interval is specified, the task must continue. It may 
optionally specify an exit routine to be given control on completion of the interval. 

The STIMER macro instruction is written as follows: 





name 


name: symbol. Begin ruune in column 1. 


b 




One or more blanks must precede STIMER. 


STIMER 




b 




One or more blanks must follow STIMER. 




REAL 

REAL,exit rtn addr 
TASK 

TASK.,exit rtn addr 
WAIT 


exit rtn addr: RX-type address, or register (0) or (2) - (12). 




,BINTVL = itor addr 
,DINTVL = j<or addr 
,GMT = stor addr 
,MICVL = 5?or addr 
,TOD = stor addr 
,T\J\l^'Yyh = stor addr 


stor addr: RX-type address, or register (1) or (2) - (12). 

Note: The GMT and TOD parameters must not be specified with 

TASK above. 




,ERRET = err rtn addr 


err rtn addr: RX-type address 
or register (2) - (12). 
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The parameters are explained as follows: 



REAL 

REALfexit rtn addr 
TASK 

TASK,ejcz7 rtn addr 
WAIT 

specifies whether the timer interval is a real-time interval (REAL or WAIT) or a task-time 
interval (TASK): 

For REAL, the interval is decreased continuously. If the TOD or GMT parameter is 
coded, the interval expires at the indicated time of day. 

For TASK, the interval is decreased only when the associated task is active. 

For WAIT, the interval is decreased continuously. The task is to be placed in the wait 
condition until the interval expires. 

The exit rtn addr is the address of the timer completion exit routine to be given control 
after the specified time interval expires. The routine does not get control immediately 
when the interval completes, but at some time after the interval completes, depending on 
the system's work load and the relative dispatching priority of the associated task. The 
routine must be in virtual storage when it is required. The exit routine receives control in 
the addressing mode of the caller. The contents of the registers when the exit routine is 
given control are as follows: 

Register Contents 

0-1 Control program information. 
2 - 12 Unpredictable. 

13 Address of a control-program-provided save area. 

14 Return address (to the control program). 

15 Address of the exit routine. 

The exit routine is responsible for saving and restoring registers. The exit routine executes 
as a subroutine, and must return control to the control program. Although timing 
services allows only one active time interval for a task, it does not serialize the use of an 
asynchronous timer completion exit routine. 



,BiNl\Y, = stor addr 
,DINTVL = ^?or addr 
,GMT = jror addr 
,MICYL^ stor addr 
,TOD = stor addr 
,T\Jjmyiu--storaddr 

specifies that the time be returned: 



For BINTVL, the address is in virtual storage containing the time interval. The time 
interval is presented as an unsigned 32-bit binary number; the low-order bit has a value of 
0.01 second. 
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For DINTVL, the address is a doubleword on a doubleword boundary in virtual storage 
containing the time interval. The time interval is presented as zoned decimal digits of the 
form: 



HHMMSSth, where: 



h 



HH 
MM 
SS 



is hours (24-hour clock) 

is minutes 

is seconds 

is tenths of seconds 

is hundredths of seconds 



For GMT, the address is an 8-byte area containing the Greenwich mean time at which the 
interval is to be completed. The time is presented as zoned decimal digits of the form 
HHMMSSth, as described above under DINTVL. 

For MICVL, the address is a doubleword on a doubleword boundary containing the time 
interval. The time interval is represented as an unsigned 64-bit binary number; bit 51 is 
the low-order bit of the interval value and equivalent to 1 microsecond. 

For TOD, the address is a doubleword on a doubleword boundary containing the time of 
day at which the interval is to be completed. The time of day is presented as zoned 
decimal digits of the form HHMMSSth, as described above under DINTVL. 

For TUINTVL, the address is a fullword on a fuUword boundary containing the time 
interval. The time interval is presented as an unsigned 32-bit binary number; the 
low-order bit has a value of one timer unit (approximately 26.04166 microseconds). 

Note: For the DINTVL, GMT, and TOD parameters, the zoned decimal digits are not 
checked for validity. Thus, the specification of invalid digits can result in an ABEND 
0C7, or a time interval different from that desired. 

,ERR£T = err rtn addr 

specifies the address of the routine to be given control when the STIMER function cannot 
be performed because of damaged clocks. The STIMER macro will test the return code 
and give control to the specified routine for a non-zero value. The register contents when 
the routine is given control are: 

Register Contents 

0-1 unpredictable 
2-14 unchanged 
IS return code 

If the caller does not specify ERRET, then the STIMER function will return only on 
successful completion (return code 0). If ERRET is not specified, failure due to damaged 
clock(s) will result in the abnormal termination of the caller. 

When control is returned, register 15 contains one of the following return codes: 

Hexadecimal Meanii^ 
Code 

00 Successful completion. 

08 Damaged clocks. 
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Notes: 



1. The time interval specified by an STIMER macro instruction has no relation to the time 
interval specified in an EXEC statement. 

2. If the optional exit routine address and WAIT are not specified, no indication of completion 
of the time interval is provided. 

3. The TTIMER and CPUTIMER macro instructions provide a facility for determining the 
remaining time interval associated with STIMER. 

4. The STIMER macro instruction should not be issued while a BTAM OPEN or LINE OPEN 
operation is in progress, since the BTAM OPEN LINE routines also use STIMER. STIMER 
should not be issued before invoking dynamic allocation because dynamic allocation can also 
issue STIMER. 

5. Specifying a time interval greater than 24 hours and DINTVL ( without TOD or GMT), 
BINVTL, MICVL, or TUINVL causes the time interval to be set to 24 hours. 

6. Specifying a time interval greater than 24 hours and DINTVL with TOD or GMT. causes a 
12F abend. 

The priorities of other tasks in the system can also affect the accuracy of the time interval 
measurement. If you code REAL or WAIT, the interval is decreased continuously and can 
expire when the task is not active. After the time interval expires, assuming the task is not in 
the wait condition for any other reasons, the task is placed in the ready condition and competes 
for control with the other ready tasks in the system. The additional time required before the 
task becomes active depends on the relative dispatching priority of the task. 

Example 1 

Operation: Request the user's asynchronous exit routine, located at location EXIT, to receive 
control after the number of hundredths of seconds specified at INTVLONG has elapsed in real 
time. 

STIMER REAL, EXIT, BINTVL=INTVLONG 



304 Supervisor Services and Macro Instructions 



STIMERM SET - Set Multiple Interval Timer 



The STIMERM SET macro instruction is used to set a timer to a specified time interval (less 
than 24 hours) or to an interval that will expire at a specified time of day (not to exceed 24 
hours). Up to sixteen STIMERM requests per task may be in effect at a time. Note that this 
limit of sixteen does not include time intervals established via the STIMER macro instruction 
or the set DIE function. 

The time interval is a real-time interval, measured continuously. The task may elect to either 
continue (WAIT = NO) or suspend execution (WAIT = YES). If the task elects to continue 
execution, it may optionally specify an exit routine to be given control on completion of the 
time interval. If an exit routine is specified, the task may optionally elect to pass a parameter to 
the exit routine. The optional asynchronous timer completion exit is given control when the 
time interval expires; if no asynchronous timer completion routine is specified, and 
WAIT = YES is not specified, no indication that the time interval has expired is provided. 

The standard form of the STIMERM SET macro instruction is written as follows: 



name 


name: symbol. Begin name in column 1 . 


b 


One or more blanks must precede STIMERM. 


STIMERM 




b 


One or more blanks must follow STIMERM. 


SET 




,ID = stor addr 


stor addr: A-type address or register (2) - (12). 


,BlNTyL = stor addr 


stor addr: A-type address or register (2) - (12). 


,DlWrVL = stor addr 


stor addr: A-type address or register (2) - (12). 


,GMT= stor addr 


stor addr: A-type address or register (2) - (12). 


,MICVL=5for addr 


stor addr: A-type address or register (2) - (12). 


,TOD = stor addr 


stor addr: A-type address or register (2) - (12). 


,TV1NTV1. = stor addr 


stor addr: A-type address or register (2) - (12). 


,ERRET= err rtn addr 


err rtn addr: A-ts^pe address or register (2) - (12). 


,WAIT = YES 


Defanlt: WAIT = NO 


,WAIT = NO 




,EXn=exit rtn addr 


exit rtn addr: A-type address or register (2) - (12). 




Note: EXIT must not be specified if WAIT = YES is specified. 


,PARM=5/or addr 


stor addr: A-type address or register (2) - (12). 




Note: If FARM is specified, EXIT must be specified and WAIT = YES must riot 




be specified. 


.RELATED = vfl/Me 





The parameters are explained below: 
SET 

This indicates a request to estabUsh a REAL time interval. 
,ID = addr 

specifies the address of a 4-byte area in which the identifier timer service assigns to this 
request will be returned. 



STIMERM SET - Set Multiple Interval Timer 305 



.BlNTyL stor addr 
,BINT\L = stor addr 
,GMl = stor addr 
,MICVL = j?c»/' addr 
j:OD = stor addr 
JVISTVL =stor addr 

specifies the storage address and format of the time interval: 

For BINTVL, the address of a 4-byte area containing the time interval. The time interval is 
represented as an unsigned 32-bit binary number; the low-order bit has a value of 0.01 second. 

For DINTVL, the address of an 8-byte area in virtual storage containing the time interval. The 
time interval is represented as zoned decimal digits of the form: 



HHMMSSth, where: 



HH 


is hours (24-hour dock) 


MM 


is minutes 


SS 


is seconds 


t 


is tenths of seconds 


h 


is hundredths of seconds 



For GMT, the address is an 8-byte area containing the Greenwich mean time at which the 
interval is to be completed. The time is represented as zoned decimal digits of the form 
HHMMSSth, as described previously under DINTVL. 

For MICVL, the address is an 8-byte storage area containing the time interval. The time 
interval is represented as an unsigned 64-bit binary number; bit 51 is the low-order bit of the 
interval value and equivalent to 1 microsecond. 

For TOD, the address is an 8-byte storage area containing the time of day at which the interval 
is to be completed. The time of day is represented as zoned decimal digits of the form 
HHMMSSth, as described previously under DINTVL. 

For TUINTVL, the address is a 4-byte area containing the time interval. The time interval is 
represented as an unsigned 32-bit binary number; the low-order bit has a value of one timer 
unit (approximately 26.04166 microseconds). 

Note: For the DINTVL, GMT, and TOD parameters, the zoned decimal digits are not 
checked for validity. Thus, the specification of invaUd digits can result in an ABEND 0C7, or a 
time interval different from that desired. 

,ERRET = err rtn addr 

specifies the address of the routine to be given control when the STIMERM function 
cannot be performed. If this parameter is omitted and an error is encountered, the 
invoker of the STIMERM function will be abnormally terminated. The specified error 
routine will be entered in the addressing mode of the STIMERM invoker. If the macro 
parameter list or any in-storage parameters are not accessible, the STIMERM invoker will 
be abended regardless of whether or not ERRET has been specified. 
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The register contents when the routine is given control are: 



Register Contents 

0 address of a 24-byte STIMERM parameter list 

1 unpredictable 
2-14 unchanged 
15 return code 



^EKYt^exit rtn addr 

specifies the address of an exit routine to be given asynchronous control after the 
requested timer interval expires. The system's workload and the relative dispatching 
priority of the associated task determine exactly when, after the interval completes, the 
exit routine gets control. The specified exit routine will be entered in the addressing mode 
of the STIMERM invoker. If WAIT = YES is specified, then the EXIT parameter must 
not be specified. 



Exit Routine Interface 



The timer exit routine, established with the EXIT parameter in an STIMERM macro 
instruction, receives control with the following register values: 

RO - control program information 

Rl - points to an 8-byte fetch-protected storage area below the 16Mb line and in the protect key that issued the 
STIMERM SET macro instruction. 



Rl > 

Word 1 

Word 2 



TIMER REQUEST ID 



USER PARAMETER (specified in the FARM keyword) 



R2-R12 - unpredictable 

R13 - address of a 72-byte save area provided by the control program 
R14 - return address (to control program) 
R15 - address of the exit routine 



The exit routine receives control in the addressing mode of the STIMERM issuer. 
,PARM = 5^or addr 

specifies the address of a 4-byte parameter to be passed to the exit routine when the 
requested timer interval expires. PARM = stor addr must not be specified if WAIT = YES 
is specified. If PARM = stor addr is specified, EXIT = exit rtn addr must also be specified. 

,WAIT=y£5 
,WAIT -=N0 

specifies whether the task should be suspended until the requested time interval expires. 
WAIT = YES specifies that the task should be suspended until the requested time interval 
expires. If WAIT = NO is coded, and EXIT is not specified, then no indication of timer 
expiration is given. WAIT = NO is the default. 

,RELATED = va/Me 

specifies information used to self document macro instructions by 'relating' functions or 
services to corresponding functions or services. The format and contents of the 
information specified are at the discretion of the user, and may be any valid macro 
keyword expression. 
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When control is returned, register 15 contains one of the following return codes. Note that for 
non-zero return codes, the ERRET routine if specified is given control. If ERRET is omitted, a 

non-zero return code will result in an ABEND of the STIMERM invoker; 



Hexadecimal 
Code 


Meaning 


0 


The STIMERM service completed successfully. 


8 


All time-of-day clocks in the system are inoperative. 


C 


GMT or TOD value specified exceeds 24 hours. 


10 


Parameters passed to STIMERM are invalid. 


18 


All clock comparators in the system are inoperative. 


IC 


Request would cause the limit of concurrent STIMERM SET requests 
supported for a TASK to be exceeded. 



Usage Notes: 

1 . The time interval specified by an STIMERM macro instruction has no relation to the time 
interval specified in an EXEC statement. 

2. If the optional exit routine address and WAIT = NO are not specified, no indication of 
completion of the time interval is provided. 

3. Specifying a time interval greater than 24 hours and DINTVL, BINVTL, MICVL, or 
TUINVL, causes the time interval to be set to 24 hours. 

4. Specifying a time interval greater than 24 hours with TOD or GMT, causes a 32E abend if 
ERRET is not specified. 

5. All input and output data addresses are treated as full 31 -bit addresses. 

6. The STIMERM SET parameter list may be above or below the 16Mb line. 

7. There is no interaction between the STIMER macro support and the STIMERM SET 
macro support. 

8. An exit routine will be unable to distinguish between the case where PARM = was not 
specified and the case where the specified PARM value was zero. 

9. If the macro parameter list or any in-storage parameters are not accessible, the STIMERM 
invoker will be abended regardless of whether or not ERRET has been specified. 

10. If multiple asynchronous exits are established, the exit routines may not receive control in 
the same order that the intervals expire. 

Example 1 

Operation: SET a timer to a specified time interval. Specify the address of a 4-byte area in 
which the identifier assigned by the timer service to this request will be returned. Specify that 
control should be given to an asynchronous timer completion exit named TIME when the time 
interval expires. Specify the address of a 4-byte area (containing the time interval represented 
as an unsigned 32-bit binary number) named INTERVAL. Include an error exit routine named 
ERROR. 

STIMERM SET , ID=ADDRESS ,BINTVL=INTERVAL ,EXIT=TIME ,ERRET=ERROR 
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Example 2 



Operation: SET a timer to a time interval that specifies the address of a 4-byte area in which 
the identifier assigned by timer service will be returned. Specify the address of a 8-byte area 
(containing the Greenwich mean time at which the interval is to be completed) named 
INTERVAL. Specify that the task should be suspended until the requested time interval 
expires. Include an error exit routine named EXITX. 

STIMERM SET , ID=ADDRESS , GMT=INTERVAL , WAIT=YES , ERRET=EXITX 

Example 3 

Operation: SET a timer to a time interval that specifies the address of a 4-byte area in which 
the identifier assigned by timer service will be returned. Specify the address of an 8-byte area 
(containing the time interval represented as a zoned decimal digit) in register 8. Specify the 
address of a 4-byte parameter to be passed to the exit routine when the requested time interval 
expires. Include the address of an exit error routine in register 9. 

STIMERM SET , ID= ( 7 ) , DINTVL= ( 8 ) , PARM=USERDATA , ERRET= ( 9 ) 



STIMERM SET - 
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STIMERM SET - Set Multiple Interval Timer (List Form) 

The list form of the STIMERM SET macro instruction is written as follows: 



name name: symbol. Begin name in column 1. 

b One or more blanks must precede STIMERM. 
STIMERM 

b One or more blanks must follow STIMERM. 

SET 
,MF = L 

.RELATED = va/Me 



The parameters are explained as follows: 
,MF=L 

specifies the list form of the STIMERM SET macro. If MF = L is not specified, then the 
standard form of the macro is expanded. If MF = L is specified, the only keyword 
allowed is RELATED. 

Example 1 

Operation: Estabhsh a remote STIMERM SET parameter list. 

STIMERM SET,MF=L 
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STIMERM SET — Set Multiple Interval Timer (Execute Form) 



The execute fomi of the STIMERM SET macro instruction is written as follows: 



ncone 


name.' symbol. Jjegm name in coliunii 1. 


h 


One or more blanks must precede STIMERM. 


STIMERM 




b 


One or more blanks must follow STIMERM. 


SET 




,ID =stor addr 


stor addr: A-type address or register (2) - (12). 


,BINTVL = jwr addr 


stor addr: A-type address or register (2) - (12). 


,DINTVL = stor addr 


stor addr: A-type address or register (2) - (12). 






MlCWh= stor addr 


Stor addr: A-type address or register (2) - (12). 


,10D= stor addr 


stor addr: A-type address or register (2) - (12). 


,'I\}mTWh= stor addr 


Stor addr: A-type address or register (2) - (12). 


,ERRET = err rtn addr 


err rtn addr: A-type address or register (2) - (12). 


,WAIT=YES 




,WAIT = NO 




,¥XYl = exit rtn addr 


exit rtn addr: A-type address or register (2) - (12). 


,PARM=a:tor addr 


stor addr: A-type address or register (2) - (12). 


MP = (^*ctrladdr) 


Ctrl addr: A-type address or register (1) - (12). 


,KELATED = value 





The parameters are explained in the standard form of the STIMERM SET macro instruction, 
with the following exception. 

,M¥ = (E,ctrl addr) 

specifies the execute form of the STIMERM SET macro instruction using a remote 
problem program parameter list If MF=(E,ctrl addr) is not specified, then the standard 
form of the macro is expanded. 

Example 1 

Operation: Establish a timer to a specified time interval specifying the address of a 4-byte area 
in which the identifier assigned to this request by timer service will be returned. Specify the 
address of an 8-byte area (containing the time interval represented as an unsigned 64-bit binary 
number) in register 5. Specify the address of a program to be given asynchronous control after 
the requested timer interval expires. Specify the address of a 4-byte parameter to be passed to 
the exit routine when the requested time interval expires. Include the address of an error 
routine in register 9. 

STIMERM SET , ID= ( 4 ) , MICVL= ( 5 ) , EXIT=ROUTE , PARM=DATA , X 
MF= ( E , REMOTE ) , ERRET= ( 9 ) 



STIMERM SET — Set Multiple Interval Timer (Execute Form) 311 



STIMERM TEST 



— Test a Time Interval 



The STIMERM TEST macro instruction is used to test the remaining time interval for a timer 

request established via the STIMERM SET macro instruction. The particular timer request to 
be tested is identified via the ID = parameter, and must have been established by the current 
task. 

If TU is specified, the STIMERM TEST macro instruction causes the control program to 
return the amount of time remaining to the designated 4-byte storage area as an unsigned 32-bit 
binary number containing the number of timer units (approximately 26.04166 microseconds per 
unit) remaining in the interval. 

If MIC is specified, the remaining time is returned to the designated 8-byte storage area. Bit 51 
of the area is the low-order bit of the interval value, and is equivalent to approximately 1 
microsecond. 

If the specified (via ID = ) timer request does not exist for the current task, or has expired, the 
storage area designated by TU = or MIC = is set to 0. 

If the specified (via ID = ) timer request exists for the current task, and the calculation of the 
interval remaining results in a negative or zero time interval, the minimum positive interval will 
be returned to the user. If the specified timer request has expired, a zero time interval is 
returned. This allows the user to differentiate the case where the interval has expired, and the 
case where the interval has not yet expired, but the remaining interval is less than or equal to 
zero. 

The standard form of the STIMERM TEST macro instruction is written as follows: 



name 


name: symbol. Begin wawe in column 1. 


b 


One or more blanks must precede STIMERM. 


STIMERM 




b 


One or more blanks must follow STIMERM. 


TEST 




,ID = stor addr 


stor addr: A-type address or register (2) - (12). 


,TU = stor addr 
,MIC = stor addr 


stor addr: A-type address or register (2) - (12). 
stor addr: A-t}^e address or register (2) - (12). 


,ERRET = err rtn addr 


err rtn addr: A-type address or register (2) - (12). 


,RELATED = value 





The parameters are explained below. 
TEST 

This indicates a request to return the remaining time for a request made using the 
STIMERM SET option. 

,ID = stor addr 

specifies the address of a 4-byte area containing the identifier assigned by the timer service 
routine to a particular timer request. 



312 Supervisor Services and Macro Instructions 



fTV — stor addr 
,MIC = stor addr 

specifies that the remaining time in the interval be returned: 

For TU, the time is returned to the specified 4-byte area as an unsigned 32-bit binary 
number. The low-order bit is approximately 26.04166 microseconds (one timer unit). 

For MIC, the time is returned in microseconds. The stor addr is the 8-byte area where the 
remaining interval is to be stored. The remaining interval is represented as an unsigned 
64-bit binary number; bit 51 is equivalent to 1 microsecond. 

The stor addr is the area where the remaining interval is to be stored. TU and MIC are 
mutually exclusive. 

,ERRET = err rtn addr 

specifies the address of the routine to be given control when the STIMERM function 
cannot be performed. If this parameter is omitted and an error is encountered, the 
STIMERM issuer will be abnormally terminated. The specified error routine will be 
entered in the AMODE of the STIMERM invoker. 

If the macro parameter list or any in-storage parameters are not accessible, the 
STIMERM invoker will be abended regardless of whether or not an ERRET = has been 
specified. 

The register contents when the routine is given control are: 

Register Contents 

0-1 unpredictable 
2-14 unchanged 
15 return code 

,RELATED = va/Me 

specifies information used to self document macro instructions by 'relating' functions or 
services to corresponding functions or services. The format and contents of the 
information specified are at the discretion of the user, and may be any valid macro 
keyword expression. 

Return Codes 

When control is returned, register 15 contains one of the following return codes. Note that for 
non-zero return codes, the ERRET routine if specified, is given control. If ERRET is omitted, a 
non-zero return code results in an abnormal termination of the STIMERM invoker. 



Hexadecimal 


Meaning 


Code 




0 


The STIMERM service has completed successfully. 


8 


All time-of-day clocks in the system are inoperative. 


10 


Parameters passed to STIMERM are invalid. 


24 


An invalid STIMERM ID number (either 0, or greater than the highest ID 




assigned by the system) has been specified. 
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Usage Notes: 



1. All input and output addresses are treated as full 31 -bit addresses. 

2. The STIMERM TEST parameter list may be above or below the 16Mb line. 

3. There is no interaction between the TTIMER macro support and the STIMERM TEST 
macro support. A time interval established via the STIMER macro cannot be tested with 
the STIMERM TEST macro instruction. Similarly, a time interval established via the 
STIMERM SET macro cannot be tested with the TTIMER macro instruction. 

4. If the macro parameter list or any in-storage parameters are not accessible, the STIMERM 
invoker will be abended regardless of whether or not an ERRET == has been specified. 

Example 1 

Operation: Test the remaining time interval for a timer request estabUshed with the STIMERM 
SET macro instruction, specifying the address of a 4-byte area (register 4) from which the 
identifier assigned to this request by the timer service will be obtained. Specify that the time be 
returned in a 4-byte area as an unsigned 32-bit binary number at the address labeled 
INTERVAL. Include the address of an exit error routine called XYZ. 

STIMERM TEST,ID=(4) ,TU= INTERVAL, ERRET=XYZ 

Example 2 

Operation: Test the remaining time interval for a timer request established with the STIMERM 
SET macro instruction, specifying the address of a 4-byte area at the address labeled ADDR 
from which the identifier assigned to this request by timer service will be obtained. Specify that 
the time be returned in microseconds in a 8-byte area as an unsigned 64-bit binary number at 
the address labeled INTERVAL. Include the address of an exit error routine called 
ERRORADD. 

STIMERM TEST , ID=ADDR ,MIC=INTERVAL , ERRET=ERRORADD 
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STIMERM TEST - Test a Time Interval (List Form) 

The list form of the STIMERM TEST macro instruction is written as follows: 



name name: symbol. Begin name in column 1. 

b One or more blanks must precede STIMERM. 
STIMERM 

b One or more blanks must follow STIMERM. 

TEST 
,MF = L 

.RELATED = va/Me 



The parameters are explained as follows: 
,MF = L 

specifies a list form macro. If MF = L is not specified, then the standard form of the 
macro is expanded. If MF = L is specified, the only keyword allowed is RELATED = . 

Example 1 

Operation: EstabUsh a remote STIMERM TEST or CANCEL parameter Ust. 

STIMERM TEST,MF=L 
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STEMERM TEST — Test a Time Interval (Execute Fonn) 



The execute form of the STIMERM TEST macro instruction is written as follows: 



name 


name: symbol. Begin name in column 1. 


b 


One or more blanks must precede STIMERM. 


STIMERM 




b 


One or more blanks must follow STIMERM. 


TEST 




,YD=stor addr 


stor addr: A-type address or register (2) - (12). 


,TU = stor addr 


star addr: A-type address or register (2) - (12). 


,MIC =stor addr 


stor addr: A-type address or register (2) - (12). 


,ERRET = err rtn addr 


err rtn addr: A-type address or register (2) - (12). 


,WP = (^,ctrladdr) 


Ctrl addr: A-type address or reg (0), or (2) - (12). 


.RELATED = value 





The parameters are explained under the standard form of the STIMERM TEST macro 
instruction with the following exception: 

fMF^'iE.ctrl addr) 

specifies an execute form of the STIMERM STEST macro instruction using a remote 
problem program parameter list. If MF = (E,ctrl addr) is not specified, then the standard 
form of tJie macro is expanded. 

Example 1 

Operation: Test the remaining time interval for a timer request estabUshed with the STIMERM 
SET macro instruction, specifying the address of a 4-byte area at the address named ADDR in 
which the identifier assigned by timer service to this request will be returned. Specify that 
register 3 will point to the appropriate list. Specify that the time be returned in microseconds in 
a 8-byte area as an unsigned 64-bit binary number at the address named INTERVAL. Include 
the address of an exit error routine called ERR. 

STIMERM TEST,ID=ADDR,MIC=INTERVAL,MF=(E, (3) ) ,ERRET=ERR 
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STIMERM CANCEL — Cancel a Timer Request 



The STIMERM CANCEL macro instruction is used to cancel a specific timer request, (or all) 
of the current task's timer requests established via the STIMERM SET macro instruction. The 
ID = parameter is used to identify the timer request(s) to be cancelled. If a specific timer 
request is to be cancelled, then the remaining time interval for that request may optionally be 
returned to a storage area designated by the TU or MIC parameters. 

If TU is specified, the STIMERM CANCEL macro instruction causes the control program to 
return the amount of time remaining to the designated 4-byte storage area as an unsigned 32-bit 
binary number containing the number of timer units (approximately 26.04166 microsecond 
units) remaining in the interval. 

If MIC is specified, the remaining time is returned to the designated 8-byte storage area. Bit 51 
of the area is equivalent to approximately 1 microsecond. 

If the specified (via ID = ) timer request exists for the current task, and the calculation of the 
interval remaining results in a negative or zero time interval, the minimum positive interval will 
be returned to the user. If the specified timer request has expired, a zero time interval is 
returned. This allows the user to differentiate the case where the interval has expired, and the 
case where the interval has not yet expired, but the remaining interval is less than or equal to 
zero. 

If a non-zero time is returned when ID = is specified, any exit routine associated with the 
specified timer request is cancelled. 

If an invalid STIMERM ID (either 0, or greater than the highest ID assigned by the system) 
has been specified, the ERRET routine will be entered, or if ERRET is not specified, the 
STIMERM CANCEL invoker will be abnormally terminated. 

The standard form of the STIMERM CANCEL macro instruction is written as follows: 



name 


name: symbol. Begin name in column 1 . 


b 


One or more blanks must precede STIMERM. 


STIMERM 




b 


One or more blanks must follow STIMERM. 


CANCEL 




,YD = stor addr 
,ID = ALL 


stor addr: A-type address or register (2) - (12). 


,TU = stor addr 
,MIC = 


stor addr: A-type address or register (2) - (12). 

stor addr stor addr: A-type address or register (2) - (12). 


,ERRET = err rtn addr 


err rtn addr: A-type address or register (2) - (12). 


,RELATED = va/Me 





The parameters are explained below: 
CANCEL 

This indicates a request to cancel and optionally return the remaining time for a timer 
request. 
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,ID = stor addr 
,ID=ALL 

specifies the address of a 4-byte area containing the identifier assigned by the timer service 
to a particular timer request. ID = ALL results in all the current task's timer request(s) 
established by STIMERM SET being cancelled. If ALL is specified, no remaining time 
interval is returned. 

If ID = ALL is specified, then neither TU nor MIC may be specified. 

,TU 

,MIC- stor addr 

specifies that the remaining time in the interval be returned: 

For TU, the time is returned to the specified 4-byte area as an unsigned 32-bit binary 
number. The low-order bit is approximately 26.04166 microseconds (one time unit). 

For MIC, the time is returned to the specified 8-byte area. Bit 51 of the area is equivalent 
to approximately 1 microsecond. 

The stor addr is the area where the remaining interval is to be stored. 

,ERRET = err rtn addr 

specifies the address of the routine to be given control when the STIMERM function 
cannot be performed. If this parameter is omitted and an error is encountered, the 
STIMERM issuer will be abnormally terminated. The specified error routine will be 
entered in the addressing mode of the STIMERM invoker. If the macro parameter list or 
any in-storage parameters are not accessible, the STIMERM invoker will be abnormally 
terminated regardless of whether or not an ERRET routine is specified. 

The register contents when the routine is given control are: 

Register Contents 

0-1 unpredictable 
2-14 unchanged 
15 return code 

,RELATED = va/Me 

specifies information used to self document macro instructions by 'relating' functions or 
services to corresponding functions or services. The format and contents of the 
information specified are at the discretion of the user, and may be any valid macro 
keyword expression. 

Return Codes 

When control is returned, register 15 contains one of the following return codes. Note that for 
non-zero return codes, the ERRET routine if specified, is given control. If ERRET is omitted, 
a non-zero return code will result in an ABEND of the STIMERM invoker. 
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Hexadecimal 
Code 


Meaning 


0 


The STIMERM service has completed successfully. 


8 


All time-of-day clocks in the system are inoperative. The CANCEL has 
been performed, but no remaining time interval will be returned. 


10 


Parameters passed to STIMERM are invalid. 


24 


An invalid STIMERM ID (either 0, or greater than the highest ID assigned 
by the system has been specified). 



Usage Notes: 

1. All input and output addresses are treated as full 31 -bit addresses. 

2. The STIMERM CANCEL parameter list may be above or below the 16Mb line. 

3. There is no interaction between the TTIMER CANCEL macro support and the STIMERM 
CANCEL macro support. A time interval established via the STIMER macro cannot be 
cancelled with STIMERM CANCEL. 

4. If the macro parameter list or any in-storage parameters are not accessible, the STIMERM 
invoker will be abnormally terminated regardless of whether or not an ERRET routine is 
specified. 

5. If the STIMERM CANCEL specifies (via ID = ) a timer request that was established with 
the WAIT = YES parameter, the task will not be taken out of the wait condition. 

Example 1 

Operation: Cancel a timer request established with a STIMERM SET macro instruction, 
specifying the address of a 4-byte area named ADDRESS containing the identifier assigned by 
the timer service. The time interval remaining should be returned as an unsigned 32-bit binary 
number in a 4-byte area called INTERVAL. An exit error routine named ERROR is also be 
specified. 

STIMERM CANCEL , ID=ADDRESS , TU=INTERVAL , ERRET=ERROR 

Example 2 

Operation: Cancel a timer request estabhshed with a STIMERM SET macro instruction, 
specifying the address of a 4-byte area named PLACE containing the identifier assigned by the 
timer service. The time interval remaining should be returned in a 8-byte area called 
INTERVAL. An exit error routine named EXITA is also be specified. 

STIMERM CANCEL , ID=PLACE ,MIC=INTERVAL , ERRET=EXITA 

Example 3 

Operation: Cancel all the timer requests established with STIMERM SET macro instruction for 
the current task. 

STIMERM CANCEL , ID=ALL 
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STIMERM CANCEL (List Form) 

The list form of the STIMERM CANCEL macro instruction is written as follows: 



ncane name: symbol. Begin itome in column 1. 

b One or more blanks must precede STIMERM. 
STIMERM 

b One or more blanks must follow STIMERM. 

CANCEL 
,MF = L 

.RELATED = va/Me 



The parameters are explained as follows: 
,MF = L 

specifies a list form of the macro instruction. If MF = L is not specified, then the 
standard form of the macro is expanded. If MF = L is specified, the only keyword allowed 
is RELATED = . 

Example 1 

Operation: Establish the appropriate storage for the EXECUTE form of the STIMERM 
CANCEL macro instruction. 

STIMERM CANCEL, MF=L 
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STIMERM CANCEL (Execute Form) 

The execute form of the STIMERM CANCEL macro instruction is written as follows: 



name 


name: symbol. Begin name in column 1. 


b 


One or more blanks must precede STIMERM. 


STIMERM 






One or more blanks must follow STIMERM 


CANCEL 




,ID= star addr 
,ID = ALL 


stor addr: A-type address or register (2) - (12). 


,T\i = stor addr 
,yaC=stor addr 


stor addr: A-type address or register (2) - (12). 
stor addr: A-type address or register (2) - (12). 


,ERRET = err rtn addr 


err rtn addr: A-type address or register (2) - (12). 


M^ = (^,ctrladdr) 


Ctrl addr: A-type address or register (2) or (2). 


.RELATED = any value 





The parameters are explained under the standard form of the STIMER CANCEL macro 
instruction with the following exception: 

,MF = (E,crr/flJrfr) 

specifies an execute form using a remote problem program parameter list. If MF = (E,ctrl 
addr) is not specified, then the standard form of the macro is expanded. 

Example 1 

Operation: Cancel the timer request estabUshed with a STIMER SET macro instruction. 
Specify the address of a 4-byte identifier named ADDRESS, and that the time interval 
remaining be returned as an unsigned binary number in a 4-byte area named INTERVAL. 
Specify an error exit routine named ERROR. 

STIMERM CANCEL, ID=ADDRESS,TU=INTERVAL,MF=(E, (0) ) ,ERRET=ERROR 
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SYNCH — Take a Synchronous Exit to a Processing Program 



If your program is to execute in 31 -bit addressing mode, you must use the MVS/XA version of 
this macro instruction. 

The SYNCH macro instruction makes it possible for a problem state program to take a 
synchronous exit to a processing program. On entry to the processing program, the high-order 
bit, bit 0, of register 14 is set to indicate the addressing mode of the issuer of the SYNCH 
macro. If bit 0 is 0, the issuer is executing in 24-bit addressing mode; if bit 0 is 1, the issuer is 
executing in 31 -bit addressing mode. The SYNCH routine analyzes a PRB (program request 
block) and schedules execution of the requested program. After the processing program has 
been executed, the program that issued the SYNCH macro instruction regains control. 

The standard form of the SYNCH macro instruction is written as follows: 



name 


name: symbol. Begin name in column \. 


b 


One or more blanks must precede SYNCH. 


SYNCH 




b 


One or more blanks must follow SYNCH. 


entry point addr 


entry point addr: RX-type address, or register (2) - (12) or (15). 


.RESTORE = NO 
.RESTORE = YES 


Default: RESTORE = NO 


,AMODE = 24 
,AMODE = 3I 
,AMODE = DEFINED 
,AMODE = CALLER 


Default: AMODE = CALLER. 

Note: AMODE = DEFINED can be specified only 

if the entry point address is provided in 

a register. 



The paraineters are explained as follows: 
entry point addr 

specifies the address of the entry point of the processing program to receive control. 

,RESTORE = NO 
,RESTORE=YES 

specifies whether registers 2-13 are to be restored when control returns to the caller. 

,AMODE=24 
,AMODE = 31 
,AMODE = DEFINED 
,AMODE = CALLER 

specifies the addressing mode in which the requested program is to receive control. 

If AMODE = 24 is specified, the requested program will receive control in 24-bit 
addressing mode. 

If AMODE = 31 is specified, the requested program will receive control in 31 -bit 
addressing mode. 

If AMODE = DEFINED is specified, the user must provide the entry point using a 
register and not an RX-type address. The requested program will receive control in the 
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addressing mode indicated by the high order bit of the entry point address. If the bit is 
off, the requested program will receive control in 24-bit addressing mode; if the bit is set, 
the requested program will receive control in 31 -bit addressing mode. 



If AMODE = CALLER is specified, the requested program will receive control in the 
addressing mode of the caller. 

Example 1 

Operation: Take a synchronous exit to PROGRAM A. Do not restore registers 2-13 when 
control returns. 

LOAD EP=PR0GRAMA,DCB=LIB1 Load desired program 
LR R8,R0 Obtain the entry point 

SYNCH (R8) ,RESTORE=NO 

Example 2 

Operation: Take a synchronous exit to a program labeled SUBRTN and restore registers 2-13 
when control returns. 

SYNCH SUBRTN, RESTORE=YES 

Example 3 

Operation: Take a synchronous exit to the program located at the address given in register 8 
and restore registers 2-13 when control returns. Indicate that this program is to execute in 
24-bit addressing mode. 

SYNCH (8) ,RESTORE=YES,AMODE=24 

Example 4 

Operation: Take a synchronous exit to the program located at the address given in register 8 
and restore registers 2-13 when control returns. Indicate that this program is to receive control 
in the addressing mode defined by the high-order bit of its entry point address. 

SYNCH ( 8 ) , RESTORE=YES , AMODE=DEFINED 

Example 5 

Operation: Take a synchronous exit to the program located at the address given in register 8 
and restore registers 2-13 when control returns. Indicate that this program is to receive control 
in the addressing mode as the caller. 

SYNCH ( 8 ) , RESTORE=YES , AMODE=CALLER 
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SYNCH (List Fonn) 



The list form of the SYNCH macro instruction is used to construct a control program 
parameter list. 

The list form of the SYNCH macro instruction is written as follows: 



notne 

b 

SYNCH 
b 


name: symbol. Begin ncone in column 1 . 
One or more blanks must precede SYNCH. 

One or more blanks must follow SYNCH. 


.RESTORE -NO 


Defanlt: RESTORE = NO 


,RESTORE = YES 




,AMODE=24 


Default: AMODE = CALLER 


^ODE = 31 




,AMODE = DEFINED 




,AMODE = CALLER 




,MF = L 





The parameters are explained under the standard form of the SYNCH macro instruction, with 
the following exception: 

,MF = L 

specifies the list form of the SYNCH macro instruction. 



Example 1 

Operation: Use the list form of the SYNCH macro instruction to specify that registers 2-13 are 
to be restored when control returns from executing the SYNCH macro instruction and that the 
addressing mode of the program is to be defined by the high-order bit of the entry point 
address. Assimie that the execute form of the macro instruction specifies the program address. 

SYNCH ,RESTORE=YES,AMODE=DEFINED,MF=L 
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SYNCH (Execute Form) 



The execute form of the SYNCH macro instruction uses a remote control program parameter 
list that can be generated by tiie list form of SYNCH. 

The execute form of the SYNCH macro instruction is written as follows: 



name 


name: symbol. Begin name in column 1. 


h 


One or more blanks must precede SYNCH. 


SYNCH 




b 


One or more blanks must follow SYNCH. 


entry point addr 


entry point addr: RX-type address, or register (2) - (12) or (15). 


,RESTORE = NO 
.RESTORE = YES 


Default- RESTORE = NO 


,AMODE = 24 
,AMODE = 31 
,AMODE = DEFINED 
,AMODE = CALLER 


Default: AMODE = CALLER 

Note: AMODE= DEFINED can be specified only if the entry point 
address is provided in a register. 


MP = (^yCtrladdr) 


Ctrl addr: RX-type address or register (I), (2) - (12). 



The parameters are explained under the standard form of the SYNCH macro instruction, with 
the following exception: 

,MP = (^,ctrl addr) 

specifies the execute form of the SYNCH macro instruction. 



Example 1 

Operation: Use the execute form of the SYNCH macro instruction to take a synchronous exit 
to the program located at the address given in register 8 and restore registers 2-13 when control 
returns. Indicate that the program is to receive control in the same addressing mode as the 
caller and that the parameter list is located at SYNCHL2. 

SYNCH (8) ,REST0RE=YES,AM0DE=CALLER,MF=(E,SYNCHL2) 



SYNCH (Execute Form) 325 



TIME- 



Provide Time and Date 



The TIME macro instruction causes the control program to return either the local time of day 
and date, the Greenwich mean time of day and date, or the contents of the TOD clock. The 
time of day and date are only as accurate as the corresponding information entered by the 
operator, and the system response time. 

Unless STCK is specified, the date is returned in register 1 as packed decimal digits of the form 
OCYYDDDF, where: 

C is a digit representing centuries beyond the twentieth. In the years 1900 through 1999, the macro will return a 

value of C = 0. 
YY is the last two digits of the year 
DDD is the day of the year 

F is a 4-bit sign character that allows the data to be unpacked and printed 

The time of day, based on a 24-hour clock, is returned in different forms, as designated by the 
parameters shown below. For the DEC, BIN, and TU parameters, the time of day is returned 
in register 0. For the MIC and STCK parameters, the time of day and TOD clock contents 
respectively are stored at the specified address. 

The TIME macro instruction is written as follows: 



The parameters are explained as follows: 



mane 


name: symbol. Begin «a/we in column 1. 


b 


One or more blanks must precede TIME. 


TIME 




b 


One or more blanks must follow TIME. 


DEC 


Default: DEC 


BIN 


stor addr: RX-type address or register (0) or (2) - (12). 


TU 




MIC,stor addr 




STCK,stor addr 




,ZONE = LT 


Defaolt: ZONE = LT 


,ZONE = GMT 


Note: This parameter has no meaning if STCK above is specified. 


,ERRET = err rtn addr 


err rtn addr: A-type address, or register (2) - (12). 



DEC 
BIN 

TU 

MIC ,stor addr 
STCK ,stor addr 

specifies that the time of day or TOD clock contents be returned: 

For DEC, the time of day is returned in register 0 as packed decimal digits, without a 
sign, of the form 

HHMMSSth, where: 

HH is hours (24-hour clock) 

MM is minutes 

SS is seconds 

t is tenths of seconds 

h is hundredths of seconds 
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For BIN, the time of day is returned in register 0 as an unsigned 32-bit binary number. 
The low-order bit is equivalent to 0.01 seconds. 

For TU, the time of day is returned in register 0 as an unsigned 32-bit binary number. 
The low-order bit is approximately 26.04166 microseconds (one timer unit). 

For MIC, the time of day is returned in microseconds. The stor addr is the address of an 
8-byte area in storage with bit 51 equivalent to one microsecond. 

For STCK, the contents of the TOD clock is returned as an unsigned 64-bit fixed-point 
number, where bit 51 is equivalent to 1 microsecond. The stor addr is the address of an 
8-byte area in storage. Register 1 does not contain the date on return. 

Notes: 

1. The resolution of the time-of-day clock is model dependent. See Principles of Operation 
for an explanation of the rate advancement. 

2. stor addr must be a 24-bit address. 

,ZONE = LT 
,ZONE = GMT 

specifies that the local time and date (LT) or the Greenwich mean time and date (GMT) 
is to be returned. 

,ERRET = err rtn addr 

specifies the address of the routine to be given control when the TIME function cannot be 
performed because of damaged clocks. The TIME macro will test the return code and 
give control to the specified routine for a non-zero value. The register contents when the 
routine is given control are: 

Register Contents 

0-1 unpredictable ■ 

2-14 unchanged 
15 return code 

If the caller does not specify ERRET, then the TIME function will return only on 
successful completion (return code 0). If ERRET is not specified, failure due to damaged 
clock(s) will result in the abnormal termination of the caller. 

When control is returned, register 15 contains one of the following return codes: 

Hexadecimal Meaning 
Code 

00 Successful completion 

08 Damaged clocks 
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Example 1 



Operation: Request the system to store the time-of-day clock in the address pointed to by 
register 2. The user's routine TIMEERR is to receive control if no usable time-of-day clock 
exists in the system. 

TIME STCK, (2) ,ERRET=TIMEERR 
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— Test Interval Timer 



The TTIMER macro instruction is used to test the timer interval established by an STIMER 
macro instruction. It is also used to cancel the remaining time interval. 

If TU is specified or assumed, the TTIMER macro instruction causes the control program to 
return in register 0 the amount of time remaining in a timer interval previously set by an 
STIMER macro instruction. The time remaining is returned as an unsigned 32-bit binary 
number specifying the number of timer units (approximately 26.04166 microsecond units) 
remaining in the interval. If a time interval has not been set or has already expired, register 0 
contains 0. 

If MIC is specified, the remaining time is returned to the doubleword area specified in the 
address. Bit 51 of the area is the low-order bit of the interval value and equivalent to 1 
microsecond. If a time interval has not been set or has already expired the area is set to 0. 

Note: The resolution of the timer is model dependent. See Principles of Operation for 
additional details concerning the timer facility. 

The TTIMER macro instruction is written as follows: 



name 


name: symbol. Begin name in column 1. 


b 


One or more blanks must precede TTIMER. 


TTIMER 




b 


One or more blanks must follow TTIMER. 


CANCEL 




,TU 


Default: TU 


,MIC,stor addr 


stor addr: RX-type address, or register (0) or (2) - (12). 


,ERRET= err rtn addr 


err rtn addr: RX-type address, or register (2) - (12). 



The parameters are explained as follows: 
CANCEL 

specifies that the remaining time interval and any exit routine are to be canceled. If the 
time iiiterval has already expired, the CANCEL option has no effect and a value of zero 
time remaining is returned. In this case, a specified exit will still receive control. If a 
non-zero time remaining is returned when the CANCEL option is specified, any exit 
routine is canceled. If CANCEL is not designated, the unexpired portion of the time 
interval remains in effect. 

If WAIT was coded in the STIMER macro instruction that established the interval, the 
task is not taken out of the wait condition and CANCEL is ignored. 
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,TU 

,MIC ^tor addr 

specifies that the remaining time in the interval be returned: 



For TU, the time is returned in register 0 as an unsigned 32-bit binary number. The 
low-order bit is approximately 26.04166 microseconds (one timer unit). 

For MIC, the time is returned in microseconds. The stor addr is the doubleword area on 
a doubleword boundary where the remaining interval is to be stored. 

,£RR£T = err rtn addr 

specifies the address of the routine to be given control when the TTIMER function 
cannot be perfonned because of damaged clocks. The TTIMER macro will test the 
return code and give control to the specified routine for a non-zero value. The register 
contents when the routine is given control are: 

Register Contents 

0-1 unpredictable 
2-14 unchanged 
15 return code 

If the caller does not specify ERRET, then the TTIMER function will return only on 
successful completion (return code 0). If ERRET is not specified, failure due to damaged 
clock(s) vidll result in the abnormal termination of the caller. 

When control is returned, register 15 contains one of the following return codes: 

Hexadecbnal Meaning 
Code 

00 Successful completion 

08 Damaged clocks 

Usage Notes: 

1. Time intervals estabUshed via the STIMERM SET macro instruction cannot be tested 
or cancelled with the TTIMER macro instruction. 

Example 1 

Operation: Cancel the task's current time interval. The time remaining, if any, should be 
returned in timer units in register 0. 

TTIMER CANCEL, TU 
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WAIT 



— Wait for One or More Events 



The WAIT macro instruction is used to inform the control program that performance of the 
active task cannot continue until one or more specific events, each represented by a different 
ECB (event control block), have occurred. Bit 0 and bit 1 of each ECB must be set to 0 before 
it is used. The control program takes the following action: 

• For each event that has already occurred (each ECB is already posted), the count of the 
number of events is decreased by 1. 

• If the number of events is 0 by the time the last event control block is checked, control is 
returned to the instruction following the WAIT macro instruction. 

• If the number of events is not 0 by the time the last ECB is checked, control is not returned 
to the issuing program until sufficient ECBs are posted to bring the number to 0. Control 
is then returned to the instruction following the WAIT macro instruction. 

The WAIT macro instruction is written as follows: 



name 


name: symbol. Begin name in column 1. 


b 


One or more blanks must precede WAIT. 


WAIT 




b 


One or more blanks must follow WAIT. 


event nmbr. 


event nmbr: symbol, decimal digit, or register (0) or (2) - (12). 

Default: 1 

Value range: 0-25 S 


ECB = ecb addr 
ECBLIST = ec6 list addr 


ecb addr: RX-type address, or register (1) or (2) - (12). 
ecb list addr: RX-type address, or register (1) or (2) - (12). 


,LONG = NO 
,LONG = YES 


Default: LONG=NO 


.RELATED = vc/Me 


va/ue; Any valid macro keyword specification. 



The parameters are explained as follows: 
event nmbr, 

specifies the number of events waiting to occur. 

ECB = ecb addr 

ECBLIST = ecb list addr 

specifies the address of an ECB on a fuUword boundary or the address of a virtual storage 
area containing one or more consecutive fuUwords on a fuUword boundary. Each 
fullword contains the address of an ECB; the high order bit in the last fullword must be 
set to 1 to indicate the end of the list. 

The ECB parameter is valid only if the number of events is specified as one or is omitted. 
The number of ECBs in the Ust specified by the ECBLIST form must be equal to or 
greater than the specified number of events. 

,LONG = NO 
,LONG = YES 

specifies whether the task is entering a long wait (YES) or a regular wait (NO). 
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,RELATED = va/Me 

specifies information used to self-document macro instructions by "relating" functions or 
services to corresponding functions or services. The format and contents of the 
information specified are at the discretion of the user, and may be any vaUd coding 
values. 

The RELATED parameter is available on macro instructions that provide opposite 
services (for example, ATTACH/DETACH, GETMAIN/FREEMAIN, and 
LOAD/DELETE), and on macro instructions that relate to previous occurrences of the 
same macro instructions (for example, CHAP and ESTAE). 

The RELATED parameter may be used, for example, as follows: 

WAITl WAIT 1,ECB=ECB,RELATED= ( RESUME 1, 

• WAIT FOR EVENT ' ) 



RESUMEl POST ECB , 0 ,RELATED= (WAITl , 

• RESUME WAITER ' ) 

Note: Each of these macro instructions will fit on one Une when coded, so there is no 
need for a continuation indicator. 

CAUTION 

A job step with all of its tasks in a WAIT condition is terminated upon 
expiration of the time limits that apply to it. 

Example: You have previously initiated one or more activities to be completed asynchronously 
to your processing. As each activity was initiated, you set up an ECB in which bits 0 and 1 
were set to 0. You now wish to suspend your task via the WAIT macro instruction until a 
specified number of these activities have been completed. 

Completion of each activity must be made known to the system via the POST macro 
instruction. POST causes an addressed ECB to be marked complete. If completion of the 
event satisfies the requirements of an outstanding WAIT, the waiting task is marked ready and 
will be executed when its priority allows. 

Example 1 

Operation: Wait for one event to occur (with a default count). 

WAIT ECB=WAITECB 
WAITECB DC F'O' 

Example 2 

Operation: Wait for 2 events to occur. 

WAIT 2,ECBLIST=LISTECBS 

LISTECBS DC A(ECBl) 

DC A(ECB2) 

DC X'80' 

DC AL3{ECB3) 
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Example 3 

Operation: Enter a long wait for a task. 

WAIT 1,ECBLIST=LISTECBS,L0NG=YES 



LISTECBS DC A(ECBl) 

DC A(ECB2) 

DC X'80' 

DC AL3(ECB3) 
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WTL - Write To Log 



The WTL macro instruction causes a message to be written to the system log. The message can 
include any character that can be used in a C-type (character) DC statement, and is assembled 
as a variable-length record. 

Note: The exact format of the output of the WTL macro instruction varies depending on the 
job entry subsystem (JES2 or JES3) that is being used, the output class that is assigned to the 
log at system initialization, and whether DLOG is in effect for JESS. In JES3, system log 
entries are preceded by a 23 -character prefix that includes a time stamp and routing 
information. If the combined prefix and message exceeds 126 characters, the log entry is spUt 
at the first blank or comma encountered when scanning backward from the 126th character of 
the combined prefix and message. See Operations: JESS Commands for information about the 
format of the log entry when using JES3. 

The standard form of the WTL macro instruction is written as follows: 



name name: symbol. Begin «a/ne in column 1 . 

b One or more blanks must precede WTL. 
WTL 

b One or more blanks must follow WTL. 

'msg' ntsg: Up to 126 characters. 



The parameter is explained as follows: 

'msg' 

specifies the message to be written to the system log. The message must be enclosed in 
apostrophes, which will not appear in the system log. See Figure 43 for a list of the 
printable EBCDIC characters passed to display devices or printers. 

Note: If the msg text exceeds 126 characters, truncation occurs at the last embedded blank 
before the 126th character; when there are no embedded blanks, truncation occurs after the 
126th character. 

Example I 

Operation: Write a message to the system log. 

WTL "THIS IS THE STANDARD FORMAT FOR THE WTL MACRO' 

Example 2 

Operation: Write a message constructed in the Ust form of WTL. 

WTL MF=(E, (R2) ) 
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WTL (List Form) 



The list form of the WTL macro instruction is used to construct a control program parameter 
list. The message parameter must be provided in the list form of the macro instruction. 

The list form of the WTL macro instruction is written as follows: 



name name: symbol. Begin name in column 1. 

b One or more blanks must precede WTL. 
WTL 

b One or more blanks must follow WTL. 

'msg' msg: Up to 126 characters. 
,MF=L 



The 'msg' parameter is explained under the standard form of the WTL macro instruction. A 
description of the MF parameter follows: 

,MF = L 

specifies the list form of the WTL macro instruction. 

Note: If msg text exceeds 126 characters, truncation occurs at the last embedded blank before 
the 126th character; when there are no embedded blanks, truncation occurs after the 126th 
character. 
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WTL (Execute Form) 



The execute form of the WTL macro instruction uses a remote control program parameter list. 
The parameter list can be generated by the list form of WTL. You cannot modify the message 
in the execute form. 

The execute form of the WTL macro instruction is written as follows: 



name name: symbol. Begin «ame in column 1. 

b One or more blanks must precede WTL. 
WTL 

b One or more blanks must follow WTL. 

MF=(E,cfr/ addr) Ctrl addr: RX-type address, or register (1) or (2) - (12). 



This parameter is explained as follows: 
M¥ = {^,ctrl addr) 

specifies the execute form of the WTL macro instruction. This form uses a remote 
control program parameter list. 
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WTO — Write to Operator 



The WTO macro instruction causes a message to be written to one or more operator consoles. 
WTO processing uses register 15. 

The standard form of the WTO macro instruction is written as follows: 



name name: symbol. Begin name in column 1. 

b One or more blanks must precede WTO. 
WTO 

b One or more blanks must follow WTO. 



'msg' msg: Up to 125 characters. 

('text') The permissible line types and lengths are shown below: 



('text'. line type) 

C 34 char 
L 70 char 
D 70 char 
DE 70 char 
E 

Default: D 

The maximum niunber of each line type allowed in a single WTO instructions 

is: 

1 C type 

2 L type 
10 D type 

1 DE type 
1 E type 

The maximum total number of line types allowed in one instruction is 10. 

,ROUTCDE = (roM/ing code) routing code: decimal digit from 1 to 16. The routing code is one or more 

codes, separated by commas. 

,DESC = (desc code) desc code: decimal digit from 1 to 16. The desc code is one or more codes, 

separated by commas. 



The parameters are explained as follows: 
'msg' 

{'text', line type) 

specifies the message or multiple-Une message to be written to one or more operator 
consoles. 

The first format is used to write a single-line message to the operator. In the format, the 
message must be enclosed in apostrophes, which do not appear on the console. It can 
include any character that can be used in a character (C-type) DC instruction. When a 
program issues a WTO macro instruction, the control program translates the text; only 
standard printable EBCDIC characters are passed to the display devices as shown in 
Figure 43. All other characters are replaced by blanks. Unless the console has dual-case 
capabihty, lowercase characters are converted to uppercase by the display station or 
printer and displayed or printed as uppercase characters. The message is assembled as a 
variable-length record. 
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The second and third formats are used to write a multiple-line message to the operator. 
The message can be up to ten lines long; the system truncates the message at the end of 
the tenth line. The ten-line limit does not include the control line (message IEE9321I), as 
explained under Une type C below. 

Note: If the second format is coded without repetition, for example, {'text"), the message 
appears as a single-Une message. 

The text is one Une of the multiple-line message. A line consists of a character string 
enclosed in apostrophes (which do not appear on the operator console). Any character 
valid in a C-type DC instruction can be coded. The maximum number of characters 
depends. on which line type is specified. 

Note: The left most three bytes of register zero must be zero for a multiple-line message. 
The user must ensure that this is done. 

The line type defines the type of information contained in the "text" field of each line of 
the message: 

C 

indicates that the "text" parameter is the text to be contained in the control line of the 
message. The control line normally contains a message title. C may only be coded for 
the first line of a multiple-line message. If this parameter is omitted and descriptor code 9 
is coded, the system generates a control line (message IEE932I) containing only a message 
identification number. The control line remains static during framing operations on a 
display console (provided that the message is displayed in an out-of-Une display area). 
Control lines are optional. 

L 

indicates that the "text" parameter is a label Une. Label Unes contain message heading 
information; they remain static during framing operations on a display console (provided 
that the message is displayed in an out-of-line display area). Label Unes are optional. If 
coded, lines must either immediately foUow the control line or another label line or be the 
first line of the multiple-Une message if there is no control Une. Only two label Unes may 
be coded per message. 

D 

indicates that the "text" parameter contains the information to be conveyed to the 
operator by the multiple-line message. During framing operations on a display console, 
the data Unes are paged. 

D£ 

indicates that the "text" parameter contains the last Une of information to be passed to 
the operator. 

E 

indicates that the previous Une of text was the last Une of text to be passed to the 
operator. The "text" parameter, if any, coded with a line type of E is ignored. 
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,RO\JTCDE = routing code 

specifies the routing code(s) to be assigned to the message. 

The routing codes are: 



1 


Master console action 


9 


System security 


2 


Master console information 


10 


System error/maintenance 


3 


Tape pool 


11 


Programmer information 


4 


Direct access pool 


12 


Emulators 


5 


Tape library 


13 


Reserved for customer use 


6 


Disk library 


14 


Reserved for customer use 


7 


Unit record pool 


15 


Reserved for customer use 


8 


Teleprocessing control 


16 


Reserved for future expansion 



Note: Routing codes 1, 2, 3, 4, 7, 8, and 10 cause hard copy of the message when display 
consoles are used or more than one console is active. All other routing codes may go to 
hard copy as a SYSGEN option or as a result of a VARY HARDCPY conmiand. 

yDESC = idesc code) 

specifies the message descriptor code(s) to be assigned to the message. Descriptor codes 1 
through 6 and descriptor code 1 1 are mutually exclusive. Codes 7 through 10 can be 
assigned in combination with any other code. 

The descriptor codes are: 



1 


System failure 


7 


Application program/processor 


2 


Immediate action required 


8 


Out-of-line message 


3 


Eventual action required 


9 


Operator request 


4 


System status 


10 


Dynamic status displays 


5 


Immediate command response 


11 


Critical eventual action requested 


6 


Job status 


12-16 


Reserved for future use 



Note: All WTO messages with descriptor codes of 1, 2, or 11 are action messages that 
have an @ sign printed before the first character. This indicates a need for operator 
action. 

Messages with descriptor code 7 are deleted at end of job step. 

Support for queuing messages with descriptor code 8 is by console id only. 

On operator consoles that support color, descriptor codes determine the color in which a 
message should be displayed. The colors used are described in Operations: System Commands. 

The message processing facility cannot suppress messages with descriptor codes 1, 2, 3, 5 
(except for responses from MONITOR JOBNAMES, MONITOR SESS, and MONITOR 
STATUS commands), and 1 1 . Messages with any other descriptor codes can be suppressed if 
they have been identified by an id or prefix in SYSl.PARMLIB member MPFLSTxx. 

If both the ROUTCDE and DESC parameters are omitted and the message is not a single-line 
message, the routing code specified in the OLDWTOR parameter of the system generation 
CONSOLE macro instruction is assigned, and a default of 7 is assigned as the descriptor code. 
If the OLDWTOR sysgen option is omitted, all routing codes and a descriptor code of 7 are 
assigned. Routing codes should be used with MLWTO messages. If DESC is specified with no 
ROUTCDE, the message will be queued to the hardcopy log by default. 
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When control is returned, general register 1 contains the identification number (24 bits and 
right-justified) assigned to the message. This number can be used to delete the message when it 
is no longer needed. 

Return codes from execution of a WTO using the multiple-line feature are as follows: 

Hexadecimal 



Code Meaning 

00 No errors encountered. 

04 Number of lines passed was 0; request is ignored. Number of lines passed was greater than 10; only 10 

lines are processed. Message text length for a line was less than 1; dl lines up to error line are 
processed. 

08 ID passed in register 0 does not match any on queue. Request is ignored. 

OC Invalid line type. An end has been forced at the point of the error except if the first line is an E line, in 

which case the request is ignored. 



Return codes from execution of a WTO are as follows: 

Hexadecimal 

Code Meanii^ 

30 Required resource for routing code 1 1 was not available. Request is ignored for routing code 11. If any 

other routing code is specified, the request is processed. 



Example 1 

Operation: Write a WTO message to all active consoles. 

WTO 'NDP00005 ENDED', X 
ROUTCDE= ( 1 , 2 , 3 , 4 , 5 , 6 , 7 , 8 , 9 , 10 , 11 , 12 , 13 , 14 , 15 , 16 ) , X 
DESC= ( 4 ) 



Example 2 

Operation: Write a multiple-line message to the master console if the master is receiving 
routing code 2 and to any other console receiving routing code 2. 

WTO ('text 1' ,D) r DATA LINE X 

(•text 2',DE), DATA END LINE X 

ROUTCDE= {2) , DESC= ( 4 ) 



340 Supervisor Services and Macro Instructions 



WTO (List Form) 



The list form of the WTO macro instruction is used to construct a control program parameter 
list. 

The list form of the WTO macro instruction is written as follows: 



name 


name: sjrmbol. Begin name in column 1. 


b 


One or more blanks must precede WTO. 


WTO 




b 


One or more blanks must follow WTO. 


'msg' 


msg: Up to 125 characters. 


('text') 


The permissible line types and text lengths are shown below: 



c 

L 
D 
DE 
E 

Default: D 

The maximum number of each line type allowed in a single WTO instructions 
is: 

1 C type 

2 L type 
10 D type 

1 DE type 
1 E type. 

The maximum total number of line types allowed in one instruction is 10. 

,ROlJTCDE = (routing code) routing code: decimal digit from 1 to 16. The routing code is one or more 

codes, separated by commas. 

,T>ESC = (desc code) desc code: decimal digit from 1 to 16. The desc cock is one or more codes, 

separated by commas. 

,MF = L 



34 char 
70 char 
70 char 
70 char 



The parameters are explained under the standard form of the WTO macro instruction, with the 
following exception: 

,MF = L 

specifies the Ust form of the WTO macro instruction. 
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WTO (Execute Form) 



The execute form of the WTO macro instruction uses a remote control program parameter list. 
The parameter list can be generated by the list form of WTO. The message cannot be modified 
in the execute form of the macro instruction. 

The execute form of the WTO macro instruction is written as follows: 



name name: symbol. Begin »am& in coliunn 1. 

b One or more blanks must precede WTO. 
WTO 

b One or more blanks must follow WTO. 

yiF = (E,ctrl addr) Ctrl addr: RX-type address, or register (1) or (2) - (12). 

This parameter is explained as follows: 
ME = {E,ctrl addr) 

specifies the execute form of the WTO macro instruction using a remote control program 
parameter Ust. 

Example 1 

Operation: Write a message with a pre-built parameter list pointed to by register 1. 
WTO MF=(E,(1)) 
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WTOR — Write to Operator with Reply 



This macro can be assembled compatibly between MVS/XA and MVS/370 through the use of 
the SPLEVEL macro instruction. Default processing will result in an expansion of the macro 
that operates only with MVS/XA. See the topic "Selecting the Macro Level" for additional 
information. If your program is to execute in 31 -bit addressing mode, you must use the 
MVS/XA version of this macro instruction. 

The WTOR macro instruction causes a message requiring a reply to be written to one or more 
operator consoles and the hardcopy log. The macro instruction also provides the information 
required by the control program to return the reply to the issuing program. 

The standard form of the WTOR macro instruction is written as follows: 



name 


name: symbol. Begin name in column 1. 


b 


One or more blanks must precede WTOR. 


WTOR 




b 


One or more blanks must follow WTOR. 


'msg' 


msg: Up to 122 characters. 


,reply addr 


reply addr: A-tj^pe address, or register (2) - (12). 


jreply length 


reply length: symbol, decimal digit, or register (2) - (12). The minimum length 




is 1; the maximum length is 115 when the operator enters REPLY id, 'reply' 




and 119 when the operator enters R id, 'reply'. 


,ecb addr 


ecb addr: A-type address, or register (2) - (12). 


,ROUTCDE = {routing code) 


routing code: decimal digit from 1 to 16. The routing code is one or more 




codes, separated by commas. 



The parameters are explained as follows: 
'msg' 

specifies the message to be written to the operator's console. The message must be 
enclosed in apostrophes, which do not appear on the console. It can include any 
character that can be used in a character (C-type) DC instruction. When a program 
issues a WTO macro instruction, the control program translates the text; only the 
standard printable EBCDIC characters shown in Figure 43 are passed to the display 
devices. All other characters are replaced by blanks. Unless the console has dual-case 
capability, lowercase characters are converted to uppercase by the display station or 
printer and displayed or printed as uppercase characters. The message is assembled as a 
variable-length record. 

Note: All WTOR messages are action messages. An indicator is printed before the first 
character of an action message to indicate a need for operator action. 

^reply addr 

specifies the address in virtual storage of the area into which the control program is to 
place the reply. The reply is left-justified at this address. 

^reply length 

specifies the length, in bytes, of the reply message. 
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^ecb addr 

specifies the address of the event control block (ECB) to be used by the control program 
to indicate the completion of the reply and the id of the replying console. After the 
control program receives the reply, the ECB appears as follows: 

Offset Length(bytes) Contents 

0 1 Completion code 

1 2 Reserved 

3 1 Console id in hexadecimal 

,ROUTCDE = {routing code) 

specifies the routing code(s) to be assigned to the message. 



The routing codes are: 



1 


Master console action 


9 


System security 


2 


Master console information 


10 


System error/maintenance 


3 


Tape pool 


11 


Programmer information 


4 


Direct access pool 


12 


Emulators 


5 


Tape library 


13 


Reserved for customer use 


6 


Disk library 


14 


Reserved for customer use 


7 


Unit record pool 


15 


Reserved for customer use 


8 


Teleprocessing control 


16 


Reserved for future expansion 



When control is returned, general register 1 contains the identification number (24 bits and 
right-justified) assigned to the message. This number can be used to delete the message when a 
reply is no longer needed. 



Ignored Parameters 

The parameter YyE^C — {desc code) is meaningless if coded since all WTOR messages are 
assigned descriptor codes of 7 (apphcation program/processor). 

Example 1 

Operation: Write a WTOR message to all active consoles. 

WTOR 'THIS IS WTOR NUMBER 001 REPLY , 18 ,ECB1 , X 
ROUTCDE= ( 1 , 2 , 3 , 4 , 5 , 6 , 7 , 8 , 9 , 10 , 11 , 12 , 13 , 14 , 15 , 16 ) 
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WTOR (List Form) 

The list form of the WTOR macro instruction is used to construct a control program parameter 
list. The message parameter must be provided in the list form. 

The list form of the WTOR macro instruction is written as follows: 



name name: symbol. Begin «ame in column 1 . 

b One or more blanks must precede WTOR. 
WTOR 

b One or more blanks must follow WTOR. 



'msg' msg: Up to 122 characters. 

reply addr: A-type address. 



.reply addr 

, reply length: symbol or decimal digit. The minimum length is 1; the maximum 

length is 115 when the operator enters REPLY id, 'reply' and 119 when the 
operator enters R id, 'reply'. 

,reply length 

ecb addr: A-type address. 

,ecb addr 

,ViO\iTCTiE- {routing code) routing code: decimal digit from 1 to 16. The routing code is one or more 

codes, separated by commas. 

,MF = L 

The parameters are explained under the standard form of the WTOR macro instruction, with 
the following exception: 

,MF=L 

specifies the list form of the WTOR macro instruction. 
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WTOR (Execute Form) 



The execute form of the WTOR macro instruction uses a remote control program parameter 
list. The parameter list can be generated by the list form of WTOR. 

The execute form of the WTOR macro instruction is written as follows: 



name 


name: symbol. Begin «a/Me in column 1 . 


h 


One or more blanks must precede WTOR. 


WTOR 




b 


One or more blanks must follow WTOR. 


,repfy addr 


reply addr: RX-type address, or register (2) - (12). 


^epfy length 


reply length: symbol, decimal digit, or register (2) - (12). The minimum length 
is 1; the maximum length is 115 when the operator enters REPLY id, 'reply' 
and 119 when the operator enters R id, 'reply'. 


,ecb addr 


ecb addr: RX-type address, or register (2) - (12). 


M^ = i^,ctrladdr) 


Ctrl addr: RX-type address, or register (1) or (2) - (12). 



The parameters are explained under the standard form of the WTOR macro instruction, with 
the following exception: 

,MF = iE,ctrl addr) 

specifies the execute form of the WTOR macro instruction using a remote control 
program parameter list. The parameter list must be aligned on a fuUword boundary. The 
list form of WTOR provides this alignment. 
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XCTL — Pass Control to a Program in Another Load Module 



If your program is to execute in 31-bit addressing mode, you must use the MVS/XA version of 
this macro instruction. 

The XCTL macro instruction causes control to be passed to a specified entry name in another 
load module; the entry name must be a member name, an alias in a directory of a partitioned 
data set, or must have been specified in an IDENTIFY macro instruction. The control 
program brings the load module containing the entry name into storage if a usable copy is not 
already available. XCTL handles the setting of the addressing mode when passing control to 
this entry name. The control program reassigns the storage occupied by the load module that 
issued the XCTL if that module is no longer required. The program executing the XCTL 
macro instruction is logically removed as a subprogram of the program (system or user) that 
placed the issuer of XCTL into execution. 

No return is made to the program issuing the XCTL macro instruction; the use count for the 
load module containing the XCTL macro instruction is decremented by 1. A return to the 
program that placed the issuer of XCTL into execution is required for successful completion of 
the task. For this reason, registers 2 through 14, the program interruption control area, and the 
program mask must be restored to the state that existed when the load module received control 
before the XCTL macro instructioii can be issued. If the specified entry cannot be located, the 
task is abnormally terminated. 

On entry to the program specified in the XCTL macro, the high-order bit, bit 0, of register 14 is 
set to indicate the addressing mode of the issuer of the macro. If bit 0 is 0, the issuer is 
executing in 24-bit addressing mode; if bit 0 is 1, the issuer is executing in 31 -bit addressing 
mode. 

The standard form of the XCTL macro instruction is written as follows: 



name 


name: symbol. Begin «flme in column 1 . 


h 


One or more blanks must precede XCTL. 


XCTL 




b 


One or more blanks must follow XCTL. 


(regl), 
(jegl.regl). 


regl and reg2: decimal digits in the order 2 through 12. 


EP = entry name 
EPLOC = entry name addr 
DE = list entry addr 


entry name: symbol. 

entry name addr: A-type address or register (2) - (12). 
list entry addr: A-type address, or register (2) - (12). 


,DCB = deb addr 


deb addr: A-type address, or register (2) - (12). 


,LSEARCH = NO 
,LSEARCH=YES 


Default: LSEARCH = NO 



The parameters are explained as follows: 

(regl), 
(regl,reg2), 

specifies the register or range of registers to be restored from the save area at the address 
contained in register 13. 
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EP^' entry name 
EPLOC = entry name addr 
DE = list entry addr 

specifies the entry name, the address of the entry name, or the address of a 60-byte Ust 
entry for the entry name that was constructed using the BLDL macro instruction. If 
EPLOC is coded, the name must be padded to eight bytes, if necessary. 

If an unauthorized program issues the XCTL macro instruction and the DE parameter 
specifies an entry in an authorized library, the program-supplied DE information is 
ignored for integrity reasons. Instead, contents management uses the BLDL macro 
instruction to construct a new list entry containing the DE information for the XCTL. 
The DE information supplied by an unauthorized program will also be ignored if the 
XCTL macro instruction is requesting access to a program or library that is controlled by 
the System Authorization Facility. 

Note: The task structure must not be changed via an ATTACH or DETACH between 
the issuance of the BLDL and the issuance of the ATTACH for the module, or an abend 
106 with a return code of 15 might result. 

,DCB = dcb addr 

specifies the address of the opened data control block for the partitioned data set 
containing the entry name described above. This parameter must indicate the same DCB 
used in the BLDL mentioned above. The DCB must not be defined in the program 
issuing the XCTL macro instruction. 

If the DCB parameter is omitted or if DCB = 0 is specified when the XCTL macro 
instruction is issued by the job step task, the data sets referred to by either the STEPLIB 
or JOBLIB DD statement are first searched for the entry name. If the entry name is not 
found, the link Hbrary is searched. 

If the DCB parameter is omitted or if DCB = 0 is specified when the XCTL macro 
instruction is issued by a subtask, the data sets associated with one or more data control 
blocks referred to by the TASKLIB operand of previous ATTACH macro instructions in 
the subtasking chain are first searched for the entry point name. If the entry point name 
is not found, the search is continued as if the XCTL had been issued by the job step task. 

Note: DCB must reside in 24-bit addressable storage. 

4.SEARCH = NO 
,LSEARCH = YES 

specifies whether (YES) or not (NO) you want the search hmited to the job pack area and 
the first library in the normal search sequence. 

Note: Do not use register 1 as a pointer to the parameter list passed by the module that issues 
XCTL. Use the execute form of the XCTL and pass the parameters explicitly using the 
PARAM keyword. 
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Example 1 

Operation: Pass control via the address of the entry name (XCTLEP), and have registers 2-12 
restored. Let the system determine the copy of the module to be used. 

XCTL (2,12) ,EPLOC=XCTLEP 
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XCTL (List Form) 



Two parameter lists are used in an XCTL macro instruction: a control program parameter list 
and an optional problem program parameter list. Only the control program parameter list can 
be constructed in the list form of XCTL. Address parameters to be passed in a parameter list 
to the problem program can be provided using the list form of the CALL macro instruction. 
This parameter list can be referred to in the execute form of XCTL. 

The list form of the XCTL macro instruction is written as follows: 



name 

b 

XCTL 
b 


name: symbol. Begin name in column 1. 
One or more blanks must precede XCTL. 

One or more blanks must follow XCTL. 


E¥ = entry name, 


entry name: symbol. 


EPLOC = entry name addr. 


entry name addr: A-type addresses. 


DE = list entry addr. 


list entry addr: A-type address. 


DCB = deb addr. 


deb addr: A-type address. 


LSEARCH = NO, 


Default: LSEARCH = NO 


LSEARCH = YES, 




SF = L 





The parameters are explained under the standard form of the XCTL macro instruction, with the 
following exception: 

SF = L 

specifies the list form of the XCTL macro instruction. 

Note: Coding the LSEARCH parameter causes a parameter list to be created that is different 
from the list created when LSEARCH is omitted. If you code LSEARCH in either the list or 
execute form of the macro instruction, you must code it in both forms. 
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XCTL (Execute Fom) 



Two parameter lists are used in the XCTL macro instruction: a control program parameter list 
and problem program parameter list. Either or both of these parameter lists can be remote and 
can be referred to, and modified by, the execute form of XCTL. If only the problem program 
parameter list is remote, parameters that require the control program parameter list cause that 
list to be constructed inline as part of the macro expansion. If only the control program 
parameter Ust is remote, no problem program parameters can be specified. 

The execute form of the XCTL macro instruction is written as follows: 





name 


name: symbol. Begin name in column 1. 


b 




One or more blanks must precede XCTL. 


XCTL 




b 




One or more blanks must follow XCTL. 




iregl), 
(regl.regl). 


regl and reg2: decimal digits or RX-type addresses, and in the order 2 
through 12. 




EP = entry name, 
EPLOC = entry name addr, 
DE = list entry addr. 


entry name: sjrmbol. 

entry name addr: RX-type address of register (2) - (12). 
list entry addr: RX-type address, or register (2) - (12). 




DCB = deb addr. 


deb addr: RX-type address, or register (2) - (12). 




PARAM = (addr), 
PARAM = {addr),N\. = 1 , 


addr: RX-type address, or register (2) - (12). 

addr is one or more addresses, separated by commas. For example, 

PARAM = (addr, addr. addr) 




LSEARCH=NO, 
LSEARCH = YES, 


Default: LSEARCH=NO 


MF 
SF = 
MP 


= (E,prob addr) 
--{E,ctrl addr) 

= (Ej>rob addr),SF = (E,ctrl addr) 


prob addr: RX-type address, or register (1) or (2) - (12). 
Ctrl addr: RX-type address, or register (2) - (12) or (15). 



The parameters are explained under the standard form of the XCTL macro instruction, with the 
following exceptions: 

F ARAM ^ (addr) 

PAR AM = M^/r), VL = 1 

specifies address(es) to be passed to the called program. Each address is expanded inline 
to a fuUword on a fuUword boundary, in the order designated. Register 1 contains the 
address of the first parameter when the program is given control. If this parameter is not 
coded, register 1 is not altered unless the LSEARCH parameter is coded. If LSEARCH 
is coded, the contents of register 1 are unpredictable. 

VL = 1 should be designated only if the called program can be passed a variable number 
of parameters. VL = 1 causes the high-order bit of the last address parameter to be set to 
1; the bit can be checked to find the end of the list. 

LSEARCH = NO 
LSEARCH = YES 

specifies whether (YES) or not (NO) you want the search limited to the job pack area and 
to the first Ubrary in the normal search sequence. If LSEARCH is specified and PARAM 
is not specified, the contents of register 1 are unpredictable. 
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MF = iE,prob addr) 
SF = ^,ctrl addr) 

MF = iE,prob addr%S¥ = (E,c/r/ addr) 

specifies the execute form of the XCTL macro instruction. This form uses a remote 
problem program parameter list, a remote control program parameter list, or both. 

Note: Coding the LSEARCH parameter causes a parameter list to be created that is different 
from the list created when LSEARCH is omitted. If you code LSEARCH in either the list or 
execute form of the macro instruction, you must code it in both forms. 
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of standard form 139 
use of 22, 23, 33, 36 
called programs 
definition of 3 
entry address 3 
first action to take 5 
calling program 
definition of 3 
return address 3 
save area 5 

address 3 



how used 5 

saving registers of 5 
calling sequence identifier 40 
cancel a timer request 317 
cell pool 

creating 145 

deleting 145 

obtaining 75, 145 

returning 145 

services 145 
ceUs 75 

chaining save areas 7 

changing the dispatching priority 143 

CHAP macro instruction 

description of 143 

example 144 

syntax 143 

use of 1 1 

characters printed on an MCS console 113 
check RACF authorization 248 
checking 

resource authorization 201 
CHNGDUMP command 69 
codes 

authorization 33 

completion 60 

descriptor 114 

message routing 114 

reason 60 
coding macro instructions 122, 123 
communicating with the system operator 1 
completed ECBs, list of 197 
completion codes, changing 60 
concatenated data sets 29 
concurrent requests for resources 

limiting 44 
continuation lines in macro parameter fields 
control 

See also passing control 

returning 25, 27, 37 
control points 

definition 51 
control program Unkage conventions 3 
controlling virtual storage 76 
conventions 

for passing control 8, 19 

for receiving control 8 
CPOOL macro instruction 

description 145 

example 148 

execute form 150 

hst form 149 

standard form 145 

syntax 

of execute form 150 

of list form 149 

of standard form 145 

use of 75 
CPU timer, obtaining value of 151 
CPUTIMER macro instruction 
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description of 151 
example 152 

relationship to STIMER macro 151 
return codes 152 
syntax 151 
creating 

a cell pool 145 
a subpool 78 
a task 9, 129 

an ESPIE environment 181 

an EVENTS table 194 
critical eventual action message 115 
CVTDCB byte 120 
CVTMVSE bit 120 



D 



DAE 

See dump analysis and elimination 
data control block 

deleting load modules that contain 82 

for SNAP dumps 69 
data security 50 
data sets, dump 69 
date and time of day, requesting 111 
DCB parameter 31 
DD statements required for dumps 68 
DE parameter 31 

debugging aids for calling sequences 40 

decimal digit term in macro instruction description 124 

default priority 10 

DELETE macro instruction 

description 153 

example 154 

lowering the responsibility count 82 
relationship to LOAD macro 153 
return codes 154 
syntax 153 
deleting 

a cell pool 145 
a load module 153 
an ESPIE environment 181 
an EVENTS table 194 
operator messages 117,171 
DEQ macro instruction 
description of 155 
example 158 
execute form 160 
list form 159 
return code area 1 57 
return codes 48, 157 
rules for using 42 
standard form 155 
syntax 

of execute form 160 

of list form 159 

of standard form 155 
use of 42, 46 



descriptor codes 1 14 
DETACH macro instruction 

description 161 

example 162 

return codes 162 

syntax 161 
detaching a subtask 161 
determining 

status of RACE protection 267 

the ESPIE environment 181 

which system is executing 120 
directory entry, PDS 15 
directory search 29 
dispatching priority 

assigning 10 

changing 143 
DIV (data-in-virtual) macro instruction 

linear data set 83 

performance considerations 105 

programming example 99 

reason codes 97 

retain mode 90, 92, 93, 94 

return codes 97 

rules for invoking 96 

rules for use in a task 96 

services of 
access 87 
identify 87 
map 88 
reset 92 
save 90 
unaccess 95 
unidentify 95 
unmap 93 

syntax 163 

use of 83 
DOM macro instruction 

description of 171 

example 172 

syntax 171 

use of 117 

downward incompatible macro instructions 1 19, 297 
DPMOD parameter on ATTACH 10 
DPRTY parameter on the EXEC statement 10 
dump analysis and elimination (DAE) 

providing information foir 64 
dumping services 68 
dumps 

ABEND 68 

data sets for 69 

indexes in SNAP dumps 70 

operator's effect on 69 

requesting 68 

SNAP 68,69 

summary 70 

symptom 69 

types a problem program can request 68 
duplicate 

names in unique task hbraries 31 
requests for a resource 45 
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dynamic load module structure 
advantages of 19 
description of 18, 19 



E 



ECB (event control block) 
description of 41 
initializing 196 
list of completed 196 
parameter of ATTACH 12, 13, 41 
setting 246 
end-of-task exit routine 13 
ENQ macro instruction 
description 173 
example 45, 178 
execute form 180 
list form 179 
return code area 177 
return codes 47, 177 
rules for using 42, 173 
standard form 174 
syntax 

of execute form 180 

of list form 179 

of standard form 174 
use of 36, 42 
entry point 
adding 40 
address 

AMODE indicator 17, 227 

of a loaded module 33 

specifying 3 
identifier 40 
identifying 22 
using aliases 40 
EP parameter 30 

EPIE (extended program interruption element) 57 
EPLOC parameter 30 
error processing 59, 61-63 

ESD (external symbol dictionary), AMODE/RMODE 

indicators 1 5 
ESPIE environment 
deleting 54, 181 
determining 181 
establishing 54, 181 
ESPIE macro instruction 
description 181 
examples 

of ESPIE RESET 184 
of ESPIE SET 183 
of ESPIE TEST 185 
of the execute form 187 
of the list form 186 
execute form 187 
list form 186 ■ 
options 

RESET 56, 183 



SET 56, 181 

TEST 56, 184 
return codes 

from ESPIE RESET 183 

from ESPIE SET 182 

from ESPIE TEST 185 
syntax 

of ESPIE RESET 183 

of ESPIE SET 181 

of ESPIE TEST 184 

of the execute form 187 

of the list form 186 
use of 53 
using 56 
establishing 

a base register 6 
an ESPIE environment 181 
ESTAE macro instruction 

addressing mode considerations 188 

description 188 

example 191 

execute form 193 

list form 192 

return codes 191 

SPLEVEL macro, use of 188 

standard form 188 

syntax 

of the execute form 193 

of the list form 192 

of the standard form 188 

use of 63 
ESTAE recovery routine 

how to use 63 

interface to 64 

pointer to parameter list created by 65 

retry processing 67 
ESTAI recovery routine 

how to use 66 

interface to 67 

retry processing 67 
ETXR parameter of ATTACH, use of 12 
event 

control block 
See ECB 

signalling completion of 41, 246 
EVENTS macro instruction 

description 194 

example 200 

parameter Ust 197 

SPLEVEL macro, use of 194 

syntax 194 

use of 41, 196 
events table 

creating 194, 196 

deleting 194, 196 

format of 196 
exclusion name lists 155, 173 
exclusive resource control 44 
EXEC statement, DPRTY parameter 10 
execute form of macro instructions 121 
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execution of load modules 19 
exit routine 

asynchronous 220 

end-of-task 13, 126 

establishing ESTAEs 188 

functions performed by 58 

register contents on entry 58 

specifying 53 

using serially reusable resources 42 
explicit requests for virtual storage 73 
extended PIE (program interruption element) 57 
extended SPIE macro instruction 

See ESPIE macro instruction 
extended STAE 

See ESTAE recovery routine 
external symbol dictionary (ESD), AMODE/RMODE 
indicators 15 



G 



0 



fake PICA 57 

fast path resource authorization checking 
finding 

a load module 29 

a save area 6 
FRACHECK macro instruction 

chart of parameters by release 203 

description 201 

execute form 206 

Ust form 205 

return codes 204 

standard form 201 

syntax 

of standard form 201 
of the execute form 206 
of the Ust form 205 

use of 51 
frames 

assigning 107 

repossessing 107 
freeing virtual storage 82, 207 
FREEMAIN macro instruction 

description 207 

example 210 

execute form 212 

list form 21 1 

return codes 210 

standard form 207 

syntax 

of the execute form 212 

of the list form 211 

of the standard form 207 

use of 73 



201 



GETMAIN macro instruction 

addressing mode considerations 213 

creating subpools 78 

description 213 

example 217 

execute form 219 

list form 218 

LOC parameter 74 

return codes 216 

standard form 213 

syntax 

of the execute form 219 

of the list form 218 

of the standard form 213 

types of 74 

use of 73,74 
gigabytes 15 

global resource serialization 44, 155, 173 
global resources 43, 44 
global symbol 297 



H 



handling abends 61 



IDENTIFY macro instruction 

description 220 

example 221 

return codes 221 

syntax 220 

use of 40 
lEECVXIT 114 
IHASDWA mapping macro 64 
immediate action message 115 
implicit requests for virtual storage 79 
inclusion name lists 155, 173 
inline parameter list, use of 22 
interface 

to a retry routine 67 

to an ESTAI routine 67 
interlock 

avoiding 49 

illustration of 49 
interruptions 

See program interruption 
interval timing, estabUshing 111 
introduction to supervisor services 1 
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job library 

reason for limiting size of 31 

use of 28 

when to define 31 
job pack area (JPA) 29 
job step task, creating 9 
JPA (job pack area) 29 



B 

last word in parameter list, how to indicate 4 

length of a loaded module 33 

library 

description of 29 

search 29 
limit priority 10, 11 
link library 28 
LINK macro instruction 

addressing mode considerations 28 

description 222 

example 224 

execute form 226 

list form 225 

standard form 222 

syntax 

of the execute form 226 
of the list form 225 
of the standard form 222 
use of 28,33,35 
when to use 82 
link pack area (LP A) 29 
linkage 

considerations for MVS/XA 16 

conventions 3 

editor 15 

registers 3 
list form of macro instructions 121 
lists 

of completed ECBs 197 

of SYSTEM inclusion resource names 155 

of SYSTEMS exclusion resource names 155 
load list area 29 
LOAD macro instruction 

description 227 

example 229 

execute form 23 1 

indicating addressing mode 28 

list form 230 

relationship to DELETE macro 153 

standard form 227 

syntax 

of the execute form 231 

of the list form 230 

of the standard form 227 



use of 28, 33, 36 
when to use 82 
load module 

adding an entry name 220 
addressing mode 33 
aliases 40 

authorization code 33 
bringing into virtual storage 227 
characteristics of 18 
deleting 153 
entry point address 33 
execution 19 

how to avoid getting an unusable copy 32 
length 33 
location 28 

more than one version 30 
names 40 

passing control to 222 
releasing control 153 
responsibility count 33, 38, 227 
searching for 29 
structure types 18 
use count 34 
using an existing copy 32 
loading 

registers and passing control 20 

virtual storage 108, 232, 242 
LOC parameter on the GETMAIN macro 74 
local resource 43 
location of a load module 28 
long wait 42 
LPA (link pack area) 29 
LPMOD parameter on ATTACH 10 



M 



machine check, recovery 59 
macro instructions 

addressing mode considerations 120-121 
coding 122, 123 
downward incompatible 119 
expansion 119 
forms of 

execute 80, 121 

list 80, 121 

standard 80, 121 
level of, selecting 119-120, 129, 188, 194, 301, 343 
reenterable form 79 
requiring caller to be in 24-bit mode 120 
requiring MVS/XA version in 31 -bit mode 121 
restrictions on using 119 
sample 123 

terms used in description of 
A-type address 124 
decimal digit 124 
default 124 
register 124 
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RX-type address 124 
symbol 123 
ways of passing parameters 79 
when can be used 119 
MCS consoles, characters displayed 113 
megabytes 15 

member names, establishing 40 
message 

critical eventual action 115 

deleting 117, 171 

descriptor codes 1 1 4 

disposition of 114 

example of WTO 115 

identifier 115 

immediate action 115 

indicator in first character 114 

multiple-line (MLWTO) 114 

replying to 116 

routing 114 

sending to operator consoles 113 

single -line 114 
MLWTO (multiple-line messages), considerations for 

using 114 
module 

See also load module 

names 9 
multiple versions of load modules 30 
multiple-line (MLWTO) messages, considerations for 

using 114 
MVS router 

description 51 

parameter list 52 
MVS router interface 261 



N 



names 

duplicate 9 

of resources 43 
nonreenterable load modules 8 1 
nonreusable load module, passing control to 37 



o 



obtaining a cell pool 145 
operator 

consoles, characters displayed 113 

messages, writing 113 
originating task 9 
overlay load module structure 18 
ownership of subpools 78 



B 

page 

faults, decreasing 107 

movement of 107 

releasing 107 

reusing 107 

size of 107 
page service list (PSL) 109 
page-ahead function 108 
paging I/O 107 

paging out virtual storage 108, 235, 242 
paging services 

input to 109 

list of 107 

PGLOAD macro instruction 232 

PGOUT macro instruction 235 

PGRLSE macro instruction 238 

PGSER macro instruction 242 
parallel execution, when to choose 9 
parameter addresses 

determining length of 120 

macros requiring 24-bit 120 
parameter area for recovery routines 59 
parameter list 

description of 20 

example of passing 21 

for macros, constructing 122 

indicating end of 22 

inline, use of 22 

location of 38, 122 

used in EVENTS processing 197 

variable length for macros 122 
parameter registers 3 
PARM field information 4 
partitioned data set directory entry 

See PDS directory entry 
passing control 

between control sections 20, 139 

between programs with different AMODEs 17, 36 

between programs with the same AMODE 17 

in a dynamic structure 28-39 
with return 33 
without return 37 

in a simple structure 19-27 
with return 22 
without return 20 

preparing to 20, 22 

to another load module 222 

using a branch instruction 22, 37 

using CALL 23 

using LINK 33 

with a parameter list 21 

with control program assistance 33 

with return 22 

without control program assistance 19, 36 
passing parameters 
in lists 20, 79 
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in registers 79 

registers used 3 
passing return addresses 20 
PDS directory entry 

AMODE indicator 15, 222 

RMODE indicator 15,16 
percolation 59, 63, 65 
performing cell pool services 145 
PGLOAD macro instruction 

description 232 

example 233 

list form 234 

page-ahead function 108 

return codes 233 

standard form 232 

syntax 

of the Hst form 234 

of the standard form 232 

use of 107 
PGOUT macro instruction 

description 235 

example 236 

list form 237 

return codes 236 

standard form 235 

syntax 

of the list form 237 

of the standard form 235 

use of 107 
PGRLSE macro instruction 

description 238 

example 239 

execute form 241 

list form 240 

return codes 238 

standard form 238 

syntax 

of the execute form 241 

of the list form 240 

of the standard form 238 

use of 107, 108 
PGSER macro instruction 

addressing mode considerations 242 

description 242 

example 245 

input to 109 

page-ahead function 108 

return codes 244 

syntax 242 

use of 108 
PICA (program interruption control area) 

format 55 

pointer to 55 

purpose of 54 

restoring a previous 55 
PIE (program interruption element) 

format of 56 

purpose of 54 
planned overlay load module structure 18 



pointer-defined entry point address 17 
post bit 41 

POST macro instruction 

description 246 

example 247 

syntax 246 

use of 41 
PRB (program request block) 40 
preparing to pass control 

with return 22 

without return 20 
priority 

address space 10 

assigning 1 1 

changing 1 1 

control program's influence on 10 

dispatching 10 

higher, when to assign 11 

limit 10, 11 

subtask 1 1 

task 10 
private library 28 
processing a resource request 44 
program check, recovery 59 
program design 19 
program exceptions 

See program interruption 
program interruption 

causes 53 

control area, see PICA and fake PICA 

determining the cause of 56 

determining the type of 58 

element, see PIE and EPIE 

handUng 53 
program management 15-40 
program mask 54 
program request block (PRB) 40 
program status word 

See PSW 
protecting resources 

via RACE 50 

via serialization 42 
providing a save area 6 
PSL (page service hst) 109 
PSW (program status word) 

addressing mode bit 16, 17 

at time of error, field containing 65 

key assigned to the requestor 76 
purging the RB queue 67 



Q 



qname of a resource 
purpose of 43, 173 
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R 



RACF 

check authorization 248 
RACF (resource access control facility) 

function of 50 

macro instructions 
FRACHECK 201 
RACSTAT 267 

protection, determining status of 267 
RACHECK macro instruction 

chart of parameters by release 254 

description 248 

examples 256 

execute form 259 

list form 257 

return codes 255 

standard form 249 

syntax 249, 257, 259 

use of 50 
RACROUTE macro instruction 

description 261 

examples 264 

execute form 266 

list form 265 

return codes 263 

standard form 262 

syntax 262 

use of 52 
RACSTAT macro instruction 

chart of parameters by release 268 

description 267 

example 269 

execute form 271 

list form 270 

of the execute form 271 

reason codes 268 

return codes 268 

syntax 

of the execute form 271 

of the Ust form 270 

of the standard form 267 

use of 51 

RB (request block), purging queue of 67 
real storage management (RSM) 107-110 
real storage, loading into virtual storage 232 
reason code 

changing 60 

field containing 65 
receiving control, conventions for 8 
recovery routine 

altering register contents 58 

altering the old PSW 58 

avoiding recursion 59 

creating your own 63 

function performed by 58 

interfaces to ESTAEs 64 

parameter area for 59 
recovery termination manager (RTM), fimction of 59 



recovery/termination services 59 
recursion, avoiding in recovery routines 59 
reenterable 

load module 32, 36, 79 

macro instructions 79 

recovery routine 63 
refreshable module 81 
REGION system parameter 73 
register 

altering the contents of 58 

contents at time of error 65 

contents for a retry routine 68 

how the control program uses 3 

linkage 3 

saving 5 

register 1, passing parameters with 20 
register 13, use of 3 
register 14 

use of 3, 22 

when to restore 20 
register 15, use of 3, 20 
registers 2-12 22 
releasing 

a resource 46 

control of a load module 153 

serially reusable resources 155 

virtual storage 107 

virtual storage contents 238, 242 
replying to WTOR messages 116 
request block (RB), purging queue of 67 
requesting 

dumps 68 

serially reusable resources 173 
requests for resources 

limiting concurrent 44 
RESERVE macro instruction 43 
residency mode of programs 

See RMODE program attribute 
resource 

checking RACF authorization 201 

class, determining RACF protection of 267 

control 41-51 

global 43 

local 43 

making duplicate requests for 45 
name lists 43, 155, 173 
naming 43 

processing a request for 44 
protecting 

via RACF 50 

via serialization 42 
releasing 46 
requesting 

conditionally 46 

exclusive control of 44 

pairs of 50 

shared control of 44 

unconditionally 46 
serially reusable 

determining status of 173 
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releasing 155 

requesting 173 

use of 42 
types that can be shared 43 
resource access control facility 
See RACF 

responsibility count for a loaded module 33, 38, 82, 

227 
restoring 

a PICA 55 

I/O operations during retry processing 67 

registers upon return 25 
retry processing 59 
retry routines 

ESTAE/ESTAI 67 

interface to 67 

register contents 68 

requirements of 67 

restoring I/O operations 67 
return address 

location of 3 

passing 20 
return code area 

used in DEQ processing 157 

used in ENQ processing 177 
return codes 

analyzing 24 

establishing 26 

from ATTACH processing 134 

from CPUTIMER processing 152 

from DELETE processing 154 

from DEQ processing 158 

from DETACH processing 162 

from ENQ processing 177 

from ESPIE TEST processing 185 

from ESTAE processing 191 

from FRACHECK processing 204 

from FREEMAIN processing 210 

from GETMAIN processing 216 

from PGOUT processing 236 

from PGRLSE processing 238 

from PGSER processing 244 

register 4 

using 24 
RETURN macro instruction 

description 272 

example 273 

return codes 272 

syntax 272 

use of 25, 26 
returning 

a cell pool 145 

control 

in a dynamic structure 37 
in a simple structure 25 
reusability attributes of a load module 36 
reusable modules 32 
reusing a save area 22 
RMODE program attribute 

affect on load processing 227 



indicator in PDS entries 15 

purpose 15 

specifying 

in source code 15 

using linkage editor control cards 15 

use of 28 

values 16 
mame of a resource, purpose of 43, 173 
routing 

codes 114 

messages 114 
RSM (real storage management) 107-110 
RTM (recovery termination manager), function of 
RX-type address 124 



s 



SAF (system authorization facihty) 51 
save area 

address, register containing 3 

chaining 7 

creating 6 

format 5 

how to tell if used 26 
passing address of 20 
reusing 22 
SAVE macro instruction 
description 274 
example 275 
syntax 274 
use of 5, 40 
saving the calling program's registers 5 
scope of a resource 

changing 43, 155, 173 
STEP, when to use 43 
SYSTEM, when to use 43 
SYSTEMS, when to use 43 
use of 43, 173 
SDWA (system diagnostic work area) 64 
changing via SETRP 59 
key fields in 

SDWACCFbit 60,65 

SDWACLUP bit 67 

SDWACMPC 60, 65 

SDWACOMU 65 

SDWACRC 60,65 

SDWADAET 65 

SDWAEBC bit 65 

SDWAECl 65 

SDWAEC2 65 

SDWAFAIN 65 

SDWAGRSV 65 

SDWAHEXbit 65 

SDWALNTH 65 

SDWAOCUR 65 

SDWAPARM 65 

SDWAREAFbit 60,65 
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SDWASPID 65 
SDWASRSV 65 
SDWAURAL 65 
SDWAVRAL 65 
length, field containing 65 
mapping macro for 64 
obtaining storage for 64 
SDWA extensions 64 
SDWAVRA 64 

searching for a load module 29-32 

areas/libraries searched 30 

limiting 30 

order of 29, 30 
security 

data (see RACF) 1 
SEGLD macro instruction 

addressing mode considerations 120 

description 276 

example 276 

syntax 276 
SEGWT macro instruction 

addressing mode considerations 120 

description 277 

example 277 

syntax 277 

selecting the macro level 119-120, 129, 188, 194, 301, 
343 

serializing resources 

avoiding an interlock 49 

requesting exclusive control 44 

requesting shared control 44 
serially reusable 

modules 

obtaining a copy of 32 
passing control to 36 

resources 

releasing 155 
requesting 173 
serializing 173 
using 42-50 
services that the supervisor provides 1 
set a multiple timer 305 
SETRP macro instruction 

description 278 

example 280 

syntax 278 

use of 59, 66 

using 60 
shared resource control 44 
sharing subpools 77, 79 
signalling completion of an event 246 
simple load module structure 18, 19 
SNAP data control block 69 
SNAP dump 

index 70 

requesting 69 
SNAP macro instruction 

description 281 

example 286, 287 

execute form 290 

list form 288 



return codes 286 
standard form 282 
syntax 

of the execute form 290 

of the list form 288 

of the standard form 282 
use of 69 
specify program interruption exit 
See SPIE 

SPIE (specify program interruption exit) environment 

addressing mode of 54 

adjusting 55 

canceling 55 

definition 54 

reestabHshing 55 
SPIE macro instruction 

addressing mode considerations 120 

addressing mode restrictions 54 

description 292 

example 294 

execute form 296 

list form 295 

standard form 293 

syntax 

of the execute form 296 

of the Hst form 295 

of the standard form 293 
use of 53, 54 
SPLEVEL macro instruction 

ATTACH macro's use of 129 

description 297 

ESTAE macro's use of 188 

EVENTS macro's use of 194 

example 298 

options 

SET 119,297 

TEST 297 
purpose of 119 
STIMER macro's use of 301 
syntax 297 

WTOR macro's use of 343 
SRM (system resource manager), function of 107 
STATUS macro instruction 

description 299 

example 300 

syntax 299 
step library 

reason for limiting size of 31 

use of 28 
STIMER macro instruction 

addressing mode considerations 301 

description 301 

example 304 

relationship to CPUTIMER macro 151 
SPLEVEL macro, use of 301 
syntax 301 
STIMERM CANCEL 
description 317 
examples 319, 320, 321 
execute form 321 
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list forai 320 

return codes 318 

standard form 317 

syntax 317, 320, 321 
STIMERM macro instructions 

use of 1 11 
STIMERM SET 

description 305 

example 308,310, 311 

execute form 311 

exit routine interface 307 

list form 310 

return codes 308 

standard form 305 

syntax 305,310,311 
STIMERM TEST 

description 312 

example 314, 315, 316 

execute form 316 

list form 315 

return codes 313 

standard form 312 

syntax 312, 315, 316 
storage 

See virtual storage 
storage request 

explicit 73 

implicit 73 
storage subpool, see subpool 76 
subpool 

creating 78 

handling 76 

IDoftheSDWA 65 

in task communication 79 

ownership of 78 

PSW key assignment 76 

sharing 77, 79 

transferring ownership 78 
subtask 

changing status of 299 

communications with tasks 1 1 

controlling 9 

creating 9 

detaching 161 

priority 1 1 

terminating 12, 41 
summary dumps 70 
supervisor services, introduction to 1 
SVC, recovery from invalid issuance 59 
switching addressing modes 

See addressing mode, changing 
symbol term in macro instruction description 123 
symptom dumps 69 
SYNCH macro instruction 

addressing mode considerations 322 

description 322 

example 

example of standard form 323 



of the execute form 325 

of the list form 324 

of the standard form 323 
execute form 325 
list form 324 
standard form 322 
syntax 

of the execute form 325 

of the list form 324 

of the standard form 322 
synchronizing tasks 41 
system authorization facility 51 
system conventions for parameter Usts 20 
system diagnostic work area 
See SDWA 

SYSTEM inclusion resource name list 43, 155, 173 
system log, writing to 116 
system resource manager (SRM), function of 107 
SYSTEMS exclusion resource name list 155, 173 
SYSUDUMP PARMLIB member 69 



s 

task 

advantage of creating additional 9 

communications with subtasks 1 1 

control block, see TCB 

creating 9, 129 

library, establishing 28 

priority, affect on processing 10 

synchronization 41 
TASKLIB parameter of ATTACH 28, 29 
tasks in a job step, illustration of 12 
TCB (task control block) 

address of 9 

removing 12 
test a time interval 312 
testing return codes 24 
time interval 

example of using 112 
TIME macro instruction 

description 326 

example 328 

syntax 326 

use of 111 
time of day and date, requesting 111 
time-of-day (TOD) clock 111 
timing services 111 
TOD (time-of-day) clock 1 1 1 
transferring control 

See passing control 
TTIMER macro instruction 

description 329 

example 330 

syntax 329 
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use count 34 
user exit routine 
See exit routine 




V-type address constant, using to pass control 22 
V = R (virtual = real) storage, allocation of 107 
variable recording area 

See VRA 
virtual storage 

allocating 213 

bringing a load module into 227 

controlling 76 

explicit requests for 73 

freeing 82, 207 

implicit requests for 79 

loading 107, 108, 232, 242 

obtaining via CPOOL 75 

page-ahead function 108, 232 

paging out 108, 235, 242 

planning for future needs 232 

releasing 107, 108, 153 

releasing contents of 238, 242 

specifying the amount allocated to a task 73 

subpools 76 

using efficiently 73 
virtual storage management (VSM) 73-82 
virtual subarea list (VSL) 109 
virtual = real (V = R) storage, allocation of 107 
VRA (variable recording area) 

length of, field containing 65 

length used, field containing 65 
VSL (virtual subarea list) 109 
VSM (virtual storage management) 73-82 



w 



wait 

bit 41 
condition 41 

long 42 
WAIT macro instruction 

description 331 

example 332, 333 

syntax 331 

use of 41 
writing 

to the operator with reply 113 
to the operator without reply 115 
to the programmer 116 



to the system log 116 
WTL macro instruction 
description 334 
example 334 
execute form 336 
list form 335 
standard form 334 
syntax 

of the execute form 336 

of the list form 335 

of the standard form 334 

use of 116 
WTO macro instruction 

description 337 

descriptor code for 115 

example 115,340,342 

execute form 342 

list form 341 

multiple-line (MLWTO) form 114 

return codes 340 

single-line form 114 

standard form 337 

syntax 

of the execute form 342 

of the list form 341 

of the standard form 337 

use of 113 
WTOR macro instruction 

addressing mode considerations 343 

description 343 

example 116,344 

execute form 346 

ignored parameters 344 

list form 345 

SPLEVEL macro, use of 343 
standard form 343 
syntax 

of the execute form 346 
of the list form 345 
of the standard form 343 
use of 113 



X 



X'538' system code 44, 173 
XCTL macro instruction 

addressing mode considerations 28, 347 

description 347 

example 349 

execute form 351 

list form 350 

lowering the responsibility count 82 

standard form 347 

syntax 

of the execute form 351 

of the Ust form 350 

of the standard form 347 



Index 365 



use of 28, 38 

using with branch instructions, danger of 38 



Numerics 



24-bit addressing mode 
description 15 

GETMAIN considerations 213 
macros requiring caller to be in 120 
restrictions on parameter addresses 121 
SPIE routine considerations 54 
31 -bit addressing mode 



description 15 

GETMAIN considerations 213 
macros requiring MVS/XA expansion 

ATTACH 129 

CALL 139 

ESTAE 188 

EVENTS 194 

LINK 222 

STIMER 301 

SYNCH 322 

WTOR 343 

XCTL 347 
SPIE considerations 54 
value of parameter addresses 120 
46D system completion code 54 



366 Supervisor Services and Macro Instructions 



I 



MVS/ Extended Architecture Supervisor Services and Macro instructions 

GC28-1 154-3 S370-36 



Printed in U.S.A. 



MVS/Extended Architecture 
Supervisor Services and 
Macro Instructions 



READER'S 

COMMENT 

FORM 



GC28-1 154-3 



This manual is part of a library that serves as a reference source for systems analysts, programmers, 
and operators of IBM systems. You may use this form to communicate your comments about this 
publication, its organization, or subject matter, with the understanding that IBM may use or distribute 
whatever information you supply in any way it beUeves appropriate without incurring any obligation to 
you. 

Note: Copies of IBM publications are not stocked at the location to which this form is addressed. Please 
direct any requests for copies of publications, or for assistance in using your IBM system, to your IBM 
representative or to the IBM branch office serving your locality. 

Possible topics for comment are: 

Clarity Accuracy Completeness Organization Coding Retrieval Legibility 
If you wish a reply, give your name, company, mailing address, and date: 



What is your occupation? 



How do you use this publication? 



Number of latest Newsletter associated with this publication: 



Thank you for your cooperation. No postage stamp necessary if mailed in the U.S.A. (Elsewhere, an 
IBM office or representative will be happy to forward your comments or you may mail directly to the 
address in the Edition Notice on the back of the title page.) 



MVS/ Extended Architecture Supervisor Services and Macro Instructions 
GC28-1 154-3 



S370-36 



Reader's Comment Form 



a. 
> 
o 

3 



Fold and tape 



Please Do Not Staple 



Fold and tape 



NO POSTAGE 
NECESSARY 
IF MAILED 
IN THE 
UNITED STATES 



BUSINESS REPLY MAIL 

FIRST CLASS PERMIT NO. 40 ARMONK, N.Y. 



POSTAGE WILL BE PAID BY ADDRESSEE 

International Business Machines Corporation 
Department D58, Building 921 -2 
PO Box 390 

Poughkeepsie, New York 1 2602 



llllillllillllllllllillllllilllllllilil 



Fold and tape Please Do Not Staple Fold and tape 



Printed in U.S.A. 




